plaita-nodes 0.3.0__tar.gz

plaita_nodes-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+# 推送 v* 标签时发布 plaita-nodes 到 PyPI。
+# 前置一次性配置：pypi.org 上为 plaita-nodes 添加 Pending Publisher，
+# owner=jeffkit repo=plaita-nodes workflow=Publish to PyPI environment=pypi
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+      - run: python -m pip install --upgrade build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

plaita_nodes-0.3.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.venv/
+mutants/
+.mutmut-cache/
+.DS_Store

plaita_nodes-0.3.0/AGENTS.md

@@ -0,0 +1,47 @@
+# AGENTS.md — plaita-nodes
+
+> plaita 通用节点集：AgentRun（经 agentproc）/ Capture / Hitl / Notify / WriteFile。
+> 大仓 ADR-2026-08-27（编排收敛 plaita + agentproc）的节点承载层。
+
+## 项目概述
+
+为 plaita 流程提供"接到真实世界"的通用节点：Agent CLI 调用（复用 flowcast 的
+agents/providers 配置，执行走 agentproc Python SDK）、本地命令、微信 HITL、通知、写文件。
+业务粘接节点（读 persona/pool 等）**不放本仓**，放业务仓（如 mediaflow/plaita_flows）。
+
+**技术栈：** Python 3.10+ · plaita（兄弟仓 editable）· agentproc（兄弟仓 editable）· requests
+**主仓库：** `git@github.com:jeffkit/plaita-nodes.git`
+
+## 架构地图
+
+依赖方向：`config.py`（flowcast 兼容配置层）← `agent_run.py`（agentproc executor 注册 + 节点）← 其余节点独立。
+对 plaita 只依赖 `plaita.Node` 基类与 `NodeExecutionContext` 窄接口；对 agentproc 只依赖 `runner.run` + `EXECUTORS` 注册表。
+
+关键路径：
+- `src/plaita_nodes/config.py` — agents/providers 加载（flowcast 搜索顺序 + 深合并 + `${VAR}` 插值 + provider→env 翻译）
+- `src/plaita_nodes/agent_run.py` — AgentRunNode + `recursive-direct` executor（语义 = flowcast runRecursiveDirect）
+- `pyproject.toml` — `[project.entry-points."plaita.nodes"]` 注册表
+
+## 开发约定
+
+**分支：** main（dev/test/prod 同支）。
+**禁止事项：**
+- 业务逻辑入仓（业务节点放业务仓）
+- 日志打印 apiKey / ANTHROPIC_AUTH_TOKEN
+- 依赖 plaita/agentproc 的内部私有 API（只走公开窄接口）
+
+**dry-run 契约：** 有副作用的节点一律尊重 `globalContext.dry_run`；writefile 例外（照常写，便于检查草稿）。
+
+## 常用命令
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## 深入阅读
+
+| 文档 | 说明 |
+|------|------|
+| `README.md` | 节点表 + 配置兼容性说明 |
+| `../docs/ADR-2026-08-27-orchestration-converge-on-plaita.md` | 决议背景 |

plaita_nodes-0.3.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: plaita-nodes
+Version: 0.3.0
+Summary: plaita 通用节点集：AgentRun（经 agentproc）/ Capture / Hitl / Notify / WriteFile
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: agentproc>=0.14.0
+Requires-Dist: plaita>=0.5.0
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'
+Provides-Extra: sql
+Requires-Dist: psycopg2-binary>=2.9; extra == 'sql'
+Requires-Dist: pymysql>=1.1; extra == 'sql'
+Requires-Dist: sqlalchemy>=2.0; extra == 'sql'
+Description-Content-Type: text/markdown
+
+# plaita-nodes
+
+plaita 的**通用节点集**（infra 级）：把 plaita 声明式流程接到真实世界——Agent CLI、本地命令、微信人工确认、通知、文件。
+
+> 背景：[ADR-2026-08-27 编排双轨收敛](../docs/ADR-2026-08-27-orchestration-converge-on-plaita.md)
+> ——编排内核收敛到 plaita，Agent 执行层统一走 agentproc；本仓是这层决议的节点承载。
+
+## 节点一览
+
+| type | 节点 | 说明 |
+|------|------|------|
+| `agentrun` | Agent 运行 | **Agent 原子**：多步工具循环（模型可调工具自主多轮）。经 [agentproc](../agentproc) 调用 Agent CLI（recursive / claude）；配置复用 flowcast 的 `agents.json` / `providers.json` |
+| `llm` | LLM 补全 | **LLM 原子**：单次 chat/completions 生成文本（OpenAI 兼容端点）。与 agentrun 的边界见下 |
+| `capture` | 命令执行 | 跑本地命令捕获输出；失败不抛错（`exit_code` 返回，流程自行分支） |
+| `hitl` | 人工确认 | 直连 hitl-server（iLink 微信通道）：发消息 → 轮询回复 |
+| `notify` | 通知 | terminal 后端（stdout） |
+| `writefile` | 写文件 | UTF-8 写文件，支持 JSON 序列化 |
+
+节点经 pyproject 的 `[project.entry-points."plaita.nodes"]` 自动注册；`plaita_nodes.register_all()` 可手动注册。
+
+## 原子节点设计原则
+
+抽象一条硬标准——**原子性**（一个节点只做一件不可再分的事）、**通用性**
+（不绑定业务语义与特定凭证）、**普适性**（覆盖一类外部交互）：
+
+- **Agent ≠ LLM**：`agentrun` 是多步工具循环的 Agent 原子（重）；`llm` 是单次
+  补全的 LLM 原子（轻）。流程里"摘要/改写/抽取/分类"用 `llm`，"多步编码/
+  工具任务"用 `agentrun`。
+- 纯文本变换（判决提取、frontmatter 解析等）**不做节点**——注册为表达式
+  `F.*` 函数（`ExpressionRegistry.register`），在 assignment 里一行使用。
+- 业务领域的状态机（如内容池销账）属于业务仓，不放本仓。
+
+## 快速上手
+
+```bash
+# monorepo 内可编辑安装（plaita / agentproc 均为兄弟仓）
+pip install -e ../plaita[http] -e ../agentproc/sdk/python -e .
+```
+
+```python
+from plaita import Flow
+
+flow = Flow.from_string(open("flow.json").read())
+result = flow.run(track="default", platforms=["twitter"], topic="", repo="/path/to/repo")
+```
+
+JSON 用法示例（agentrun + 模板表达式）：
+
+```json
+{
+  "type": "agentrun", "id": "brief",
+  "agent": "glm-52",
+  "prompt": "{% $F.concat($INPUT.item.brief_prompt) %}",
+  "next": "write"
+}
+```
+
+## agents.json / providers.json 兼容性
+
+配置搜索顺序与 flowcast 一致：`~/.flowx → ~/.flowcast → <repo>/.flowcast`（深合并）。
+
+与 flowcast 的两处行为差异（有意为之）：
+
+1. agents.json 里的 `env` 字段 flowcast 白名单会**静默丢弃**，本仓按配置透传
+   （如 glm-52 的 `RECURSIVE_MAX_TOKENS`）。
+2. recursive 直路径 flowcast 默认无超时，本仓 `timeout_secs` 默认 1800。
+
+## 设计边界
+
+- **安全**：任何日志不打 apiKey / ANTHROPIC_AUTH_TOKEN。
+- **dry-run**：所有有副作用的节点尊重 `globalContext.dry_run`——agentrun/capture/hitl 返回 fake 结果，writefile 照常写（草稿便于检查）。
+- **断点续跑**：hitl 为阻塞版（Normal 模式）；崩溃级恢复走 plaita Distributed + EventNode 模式（见 ADR phase 2）。
+- 新增执行器：在 `agentproc` executor 层扩展 + `config.EXECUTOR_ALIASES` 加映射，本仓节点无需改动。
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

plaita_nodes-0.3.0/README.md

@@ -0,0 +1,80 @@
+# plaita-nodes
+
+plaita 的**通用节点集**（infra 级）：把 plaita 声明式流程接到真实世界——Agent CLI、本地命令、微信人工确认、通知、文件。
+
+> 背景：[ADR-2026-08-27 编排双轨收敛](../docs/ADR-2026-08-27-orchestration-converge-on-plaita.md)
+> ——编排内核收敛到 plaita，Agent 执行层统一走 agentproc；本仓是这层决议的节点承载。
+
+## 节点一览
+
+| type | 节点 | 说明 |
+|------|------|------|
+| `agentrun` | Agent 运行 | **Agent 原子**：多步工具循环（模型可调工具自主多轮）。经 [agentproc](../agentproc) 调用 Agent CLI（recursive / claude）；配置复用 flowcast 的 `agents.json` / `providers.json` |
+| `llm` | LLM 补全 | **LLM 原子**：单次 chat/completions 生成文本（OpenAI 兼容端点）。与 agentrun 的边界见下 |
+| `capture` | 命令执行 | 跑本地命令捕获输出；失败不抛错（`exit_code` 返回，流程自行分支） |
+| `hitl` | 人工确认 | 直连 hitl-server（iLink 微信通道）：发消息 → 轮询回复 |
+| `notify` | 通知 | terminal 后端（stdout） |
+| `writefile` | 写文件 | UTF-8 写文件，支持 JSON 序列化 |
+
+节点经 pyproject 的 `[project.entry-points."plaita.nodes"]` 自动注册；`plaita_nodes.register_all()` 可手动注册。
+
+## 原子节点设计原则
+
+抽象一条硬标准——**原子性**（一个节点只做一件不可再分的事）、**通用性**
+（不绑定业务语义与特定凭证）、**普适性**（覆盖一类外部交互）：
+
+- **Agent ≠ LLM**：`agentrun` 是多步工具循环的 Agent 原子（重）；`llm` 是单次
+  补全的 LLM 原子（轻）。流程里"摘要/改写/抽取/分类"用 `llm`，"多步编码/
+  工具任务"用 `agentrun`。
+- 纯文本变换（判决提取、frontmatter 解析等）**不做节点**——注册为表达式
+  `F.*` 函数（`ExpressionRegistry.register`），在 assignment 里一行使用。
+- 业务领域的状态机（如内容池销账）属于业务仓，不放本仓。
+
+## 快速上手
+
+```bash
+# monorepo 内可编辑安装（plaita / agentproc 均为兄弟仓）
+pip install -e ../plaita[http] -e ../agentproc/sdk/python -e .
+```
+
+```python
+from plaita import Flow
+
+flow = Flow.from_string(open("flow.json").read())
+result = flow.run(track="default", platforms=["twitter"], topic="", repo="/path/to/repo")
+```
+
+JSON 用法示例（agentrun + 模板表达式）：
+
+```json
+{
+  "type": "agentrun", "id": "brief",
+  "agent": "glm-52",
+  "prompt": "{% $F.concat($INPUT.item.brief_prompt) %}",
+  "next": "write"
+}
+```
+
+## agents.json / providers.json 兼容性
+
+配置搜索顺序与 flowcast 一致：`~/.flowx → ~/.flowcast → <repo>/.flowcast`（深合并）。
+
+与 flowcast 的两处行为差异（有意为之）：
+
+1. agents.json 里的 `env` 字段 flowcast 白名单会**静默丢弃**，本仓按配置透传
+   （如 glm-52 的 `RECURSIVE_MAX_TOKENS`）。
+2. recursive 直路径 flowcast 默认无超时，本仓 `timeout_secs` 默认 1800。
+
+## 设计边界
+
+- **安全**：任何日志不打 apiKey / ANTHROPIC_AUTH_TOKEN。
+- **dry-run**：所有有副作用的节点尊重 `globalContext.dry_run`——agentrun/capture/hitl 返回 fake 结果，writefile 照常写（草稿便于检查）。
+- **断点续跑**：hitl 为阻塞版（Normal 模式）；崩溃级恢复走 plaita Distributed + EventNode 模式（见 ADR phase 2）。
+- 新增执行器：在 `agentproc` executor 层扩展 + `config.EXECUTOR_ALIASES` 加映射，本仓节点无需改动。
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

plaita_nodes-0.3.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "plaita-nodes"
+version = "0.3.0"
+description = "plaita 通用节点集：AgentRun（经 agentproc）/ Capture / Hitl / Notify / WriteFile"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "plaita>=0.5.0",
+    "agentproc>=0.14.0",
+    "requests>=2.31",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pyyaml"]
+sql = ["sqlalchemy>=2.0", "psycopg2-binary>=2.9", "pymysql>=1.1"]
+
+[project.entry-points."plaita.nodes"]
+agentrun = "plaita_nodes.agent_run:AgentRunNode"
+capture = "plaita_nodes.capture:CaptureNode"
+hitl = "plaita_nodes.hitl:HitlNode"
+llm = "plaita_nodes.llm:LlmNode"
+gate = "plaita_nodes.gate:GateNode"
+rate_limit = "plaita_nodes.rate_limit:RateLimitNode"
+report = "plaita_nodes.report:ReportNode"
+hitl_await = "plaita_nodes.hitl_await:HitlAwaitNode"
+notify = "plaita_nodes.notify:NotifyNode"
+writefile = "plaita_nodes.write_file:WriteFileNode"
+feishu_webhook = "plaita_nodes.webhooks:FeishuWebhookNode"
+wecom_webhook = "plaita_nodes.webhooks:WecomWebhookNode"
+slack_webhook = "plaita_nodes.webhooks:SlackWebhookNode"
+dingtalk_webhook = "plaita_nodes.webhooks:DingtalkWebhookNode"
+generic_webhook = "plaita_nodes.api:GenericWebhookNode"
+api_request = "plaita_nodes.api:ApiRequestNode"
+sql_query = "plaita_nodes.database:SqlQueryNode"
+email_send = "plaita_nodes.email:EmailSendNode"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/plaita_nodes"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

plaita_nodes-0.3.0/src/plaita_nodes/__init__.py

@@ -0,0 +1,53 @@
+"""plaita-nodes —— plaita 通用节点集（infra 级，ADR-2026-08-27）。
+
+节点通过 pyproject 的 ``[project.entry-points."plaita.nodes"]`` 自动注册；
+若以源码方式引入（未经 pip 安装），可显式调用 :func:`register_all`。
+"""
+from .agent_run import AgentRunError, AgentRunNode, extract_recursive_result, register_recursive_direct
+from .api import ApiRequestNode, GenericWebhookNode
+from .database import SqlQueryNode
+from .email import EmailSendNode
+from .capture import CaptureConfigError, CaptureNode
+from .config import (
+    EXECUTOR_ALIASES,
+    AgentConfigError,
+    interpolate,
+    load_merged_config,
+    resolve_agent,
+    resolve_provider,
+)
+from .hitl import HitlError, HitlNode
+from .gate import GateNode
+from .hitl_await import HitlAwaitNode
+from .llm import LlmError, LlmNode
+from .rate_limit import RateLimitNode
+from .report import ReportNode, append_entry, read_entries
+from .notify import NotifyNode
+from .webhooks import DingtalkWebhookNode, FeishuWebhookNode, SlackWebhookNode, WecomWebhookNode
+from .write_file import WriteFileNode
+
+__version__ = "0.3.0"
+
+_ALL_NODES = [AgentRunNode, ApiRequestNode, CaptureNode, DingtalkWebhookNode, EmailSendNode, FeishuWebhookNode, GateNode, GenericWebhookNode, HitlAwaitNode, HitlNode, LlmNode, NotifyNode, RateLimitNode, ReportNode, SlackWebhookNode, SqlQueryNode, WecomWebhookNode, WriteFileNode]
+
+
+def register_all() -> None:
+    """显式注册全部节点到默认 registry（entry_points 之外的手动路径）。"""
+    from plaita.node import get_default_registry
+
+    registry = get_default_registry()
+    for node_cls in _ALL_NODES:
+        registry.register(node_cls)
+
+
+__all__ = [
+    "AgentRunNode", "AgentRunError", "extract_recursive_result", "register_recursive_direct",
+    "CaptureNode", "CaptureConfigError",
+    "HitlNode", "HitlAwaitNode", "HitlError", "LlmNode", "LlmError", "ReportNode", "report_append", "report_read",
+    "NotifyNode",
+    "WriteFileNode",
+    "register_all",
+    "load_merged_config", "resolve_agent", "resolve_provider", "interpolate",
+    "AgentConfigError", "EXECUTOR_ALIASES",
+    "__version__",
+]

plaita_nodes-0.3.0/src/plaita_nodes/agent_run.py

@@ -0,0 +1,232 @@
+"""AgentRunNode —— 经 agentproc 调用 Agent CLI（recursive / claude / …）。
+
+设计（ADR-2026-08-27）：
+- 配置层复用 flowcast 的 agents.json / providers.json（见 config.py）；
+- 执行层走 agentproc Python SDK 的 in-process executor 机制；
+- ``recursive-direct`` 是本包注册的直调执行器，语义照搬 flowcast 的
+  ``runRecursiveDirect``：``recursive --workspace . --output-format json
+  [--model M] [--max-steps N] run "<prompt>"``，stdout 末尾为单个 JSON
+  对象，取 ``.result`` 为回复、``.is_error`` 为失败。
+- 输出：``{"text", "cli", "session_id", "usage", "dry_run"}``，
+  下游用 ``$NODE.<id>.text`` 引用。
+
+日志脱敏：任何路径都不打印 apiKey / ANTHROPIC_AUTH_TOKEN。
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from typing import Any, ClassVar, Optional
+
+from pydantic import Field
+
+from plaita import Node
+
+from .config import EXECUTOR_ALIASES, resolve_agent
+
+
+class AgentRunError(RuntimeError):
+    pass
+
+
+# ── recursive 直调执行器（语义 = flowcast runRecursiveDirect）──────────
+
+def _make_recursive_handlers():
+    def build_args(message: str, session_id: str, env: dict) -> list:
+        bin_name = env.get("RECURSIVE_BIN", "recursive")
+        args = [bin_name, "--workspace", env.get("RECURSIVE_WORKSPACE", "."),
+                "--output-format", "json"]
+        if env.get("RECURSIVE_MODEL"):
+            args += ["--model", env["RECURSIVE_MODEL"]]
+        if env.get("RECURSIVE_MAX_STEPS"):
+            args += ["--max-steps", str(env["RECURSIVE_MAX_STEPS"])]
+        args += ["run", message]
+        return args
+
+    return {"build_args": build_args}
+
+
+def register_recursive_direct() -> None:
+    from agentproc import EXECUTORS
+
+    if "recursive-direct" not in EXECUTORS:
+        EXECUTORS["recursive-direct"] = {
+            "cli_name": "recursive",
+            "install_hint": "brew install kongjie/tap/recursive（或 cargo build --release）",
+            # plain：stdout 整体作为 reply（recursive --output-format json 输出单个
+            # JSON 对象而非 NDJSON），由本节点再做 .result 提取。
+            "plain": True,
+            "make_handlers": _make_recursive_handlers,
+        }
+
+
+register_recursive_direct()
+
+
+def extract_recursive_result(stdout: str) -> dict:
+    """从 recursive 的 stdout 提取末尾 JSON 对象（``--output-format json`` 为
+    “单个结果对象收尾”）。
+
+    策略：优先取**行首 ``{`` 起始**的最后一个可解析对象（日志噪声多出现在行中）；
+    退回首个 ``{"`` 的括号配对扫描（跳过字符串内花括号，与 flowcast
+    extractRecursiveJson 同款）；全部失败则把原文当 result 返回。
+    """
+    line_starts: list[int] = []
+    lines = stdout.split("\n")
+    offset = 0
+    for line in lines:
+        if line.lstrip().startswith("{"):
+            line_starts.append(offset)
+        offset += len(line) + 1
+    find_idx = stdout.find('{"')
+
+    # 扫描顺序：行首对象从后往前优先（结果对象在末尾），find('{"') 兜底
+    scan_order = list(reversed(line_starts))
+    if find_idx >= 0:
+        scan_order.append(find_idx)
+
+    for start in scan_order:
+        depth = 0
+        in_string = False
+        escaped = False
+        for i in range(start, len(stdout)):
+            ch = stdout[i]
+            if in_string:
+                if escaped:
+                    escaped = False
+                elif ch == "\\":
+                    escaped = True
+                elif ch == '"':
+                    in_string = False
+                continue
+            if ch == '"':
+                in_string = True
+            elif ch == "{":
+                depth += 1
+            elif ch == "}":
+                depth -= 1
+                if depth == 0:
+                    try:
+                        return json.loads(stdout[start:i + 1])
+                    except json.JSONDecodeError:
+                        break
+    return {"result": stdout, "is_error": False, "raw": True}
+
+
+class AgentRunNode(Node):
+    """运行一个 Agent CLI 并返回其文本回复。
+
+    JSON 字段：
+    - ``agent``: agents.json 里的名字（默认 ``glm-52``），支持表达式
+    - ``prompt``: prompt 文本，支持 ``{% ... %}`` 模板表达式
+    - ``repo``: 工作目录（recursive 的 ``--workspace``；默认进程 cwd）
+    - ``timeout_secs``: 超时秒数（默认 1800；flowcast 的 recursive 直路径无超时，
+      这里是行为改进）
+    - ``dry_run``: 为 true（或流程 globalContext.dry_run=true）时不真正调用，
+      返回 fake 文本
+
+    输出：``{"text", "cli", "session_id", "usage", "dry_run"}``。
+    """
+
+    node_type: ClassVar[str] = "agentrun"
+    node_name: ClassVar[str] = "Agent 运行"
+
+    agent: Optional[Any] = "glm-52"
+    prompt: Optional[Any] = None
+    repo: Optional[Any] = None
+    timeout_secs: int = Field(default=1800)
+    dry_run: bool = False
+
+    def execute(self, execution: Any) -> dict:
+        agent_name = str(execution.evaluate(self.agent)) if self.agent is not None else "glm-52"
+        prompt = execution.evaluate(self.prompt) if self.prompt is not None else ""
+        repo = execution.evaluate(self.repo) if self.repo else None
+        dry = self.dry_run or bool(execution.get_global_variable("dry_run", False))
+
+        if dry:
+            preview = prompt[:80] + ("…" if len(prompt) > 80 else "")
+            return {"text": f"[dry-run] {agent_name} would run: {preview}",
+                    "cli": agent_name, "session_id": "", "usage": None, "dry_run": True}
+
+        profile = resolve_agent(agent_name, repo=repo)
+        executor = profile["executor"]
+
+        from agentproc import EXECUTORS as AP_EXECUTORS
+
+        # 显式别名映射优先；否则若 agentproc 已内置同名 executor（或测试桩）直接使用
+        ap_executor = EXECUTOR_ALIASES.get(executor, executor)
+        if ap_executor not in AP_EXECUTORS:
+            raise AgentRunError(
+                f"执行器 '{executor}' 未接入（agentproc 可用：{sorted(AP_EXECUTORS)}）；"
+                f"如需其他 CLI 请在 agentproc executor 层扩展或加 EXECUTOR_ALIASES 映射"
+            )
+
+        from agentproc.runner import RunOptions
+        from agentproc.runner import run as agentproc_run
+
+        extra_env = dict(profile["env"])
+        extra_env.setdefault("RECURSIVE_WORKSPACE", repo or ".")
+        result = agentproc_run(
+            {"executor": ap_executor},
+            RunOptions(message=str(prompt), extra_env=extra_env,
+                       timeout_secs=self.timeout_secs),
+        )
+        if result.error or result.exit_code != 0:
+            raise AgentRunError(result.error or f"{agent_name} 退出码 {result.exit_code}")
+
+        text = result.reply
+        if executor == "recursive":
+            parsed = extract_recursive_result(result.reply)
+            if parsed.get("is_error"):
+                raise AgentRunError(f"recursive is_error: {str(parsed.get('result'))[:300]}")
+            text = str(parsed.get("result") or "")
+
+        return {"text": text, "cli": executor, "session_id": result.session_id,
+                "usage": result.usage, "dry_run": False}
+
+
+def recursive_stream_turn(task: str, *, workspace: str, profile: str = "glm-52",
+                          model: Optional[str] = None,
+                          max_steps: Optional[int] = None,
+                          timeout_secs: int = 1800):
+    """以流式方式跑一轮 recursive Agent（生成器：yield 事件 dict）。
+
+    事件序列：
+        {"type": "line", "text": str}            # agent 原始输出行（宿主可实时展示）
+        {"type": "done", "ok": bool, "result": str, "error": str}
+    供宿主进程（如 plaita-console 的 AI 流程生成）把编码 Agent 作为生成后端复用。
+    """
+    import time as _time
+
+    register_recursive_direct()
+    agent = resolve_agent(profile)
+    env_extra = dict(agent["env"])
+    env_extra.setdefault("RECURSIVE_WORKSPACE", workspace)
+    if model:
+        env_extra["RECURSIVE_MODEL"] = model
+    handlers = _make_recursive_handlers()
+    if agent.get("model"):
+        env_extra.setdefault("RECURSIVE_MODEL", agent["model"])
+    argv = handlers["build_args"](task, "", env_extra)
+    # 子进程必须拿到 provider 凭证 env（否则无凭证运行得到空回复）
+    proc_env = {**os.environ, **env_extra}
+    proc = subprocess.Popen(argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                            text=True, cwd=workspace, env=proc_env)
+    lines: list[str] = []
+    deadline = _time.monotonic() + timeout_secs
+    for line in proc.stdout:  # type: ignore[union-attr]
+        yield {"type": "line", "text": line.rstrip("\n")}
+        lines.append(line)
+    proc.wait()
+    timed_out = _time.monotonic() > deadline
+    stdout = "".join(lines)
+    if timed_out:
+        yield {"type": "done", "ok": False, "result": "", "error": f"agent 超时（>{timeout_secs}s）"}
+        return
+    parsed = extract_recursive_result(stdout)
+    if parsed.get("is_error"):
+        yield {"type": "done", "ok": False, "result": "",
+               "error": f"recursive is_error: {str(parsed.get('result'))[:300]}"}
+        return
+    yield {"type": "done", "ok": True, "result": parsed.get("result") or "", "error": ""}