dynworkflow 0.1.0__py3-none-any.whl

dynworkflow/reporter.py

@@ -0,0 +1,250 @@
+# coding: utf-8
+"""基于 stdio 输出的 JSONL 状态上报。
+
+工作流运行期间把四类事件以 JSONL（每行一个 JSON 对象）写到 stdout：
+
+- ``graph``：``Flow.execute`` 生成的流程图（nodes/edges/start）；
+- ``node``：节点状态变更（running/done/error，含全部已填充参数，
+  缓存命中同样推送并以 ``cached`` 标记）；
+- ``agents_start``：节点即将启动 Agent/MultiAgent（含本次调用的
+  序号、prompt 列表）；
+- ``agent``：子 Agent 的实时状态（waiting/running/success/failure、
+  工具调用列表、session id、所属节点与序号等），每次状态变化立即上报；
+- ``node_code``：节点启动时广播其源码；
+- ``node_log``：节点线程内 ``print`` 的输出转发（替换内置 print 实现，按 ``\n`` 成行缓冲，正确处理多参数、sep、end 与 flush）。
+
+每次输出 JSONL 时，先写入 ``\\x1b[?2004h``、结尾写入 ``\\x1b[?2004l``，
+把整块上报输出包裹为宿主可识别的区段。上报过程绝不抛出异常干扰工作流执行。
+"""
+
+from __future__ import annotations
+
+import builtins
+import json
+import sys
+import threading
+from collections.abc import Iterable
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, TextIO
+
+if TYPE_CHECKING:
+    from .agent import AgentStatusSingleAgent
+    from .flow import Graph
+
+BRACKETED_PASTE_ENABLE = "\x1b[?2004h"  # JSONL 输出块起始标记
+BRACKETED_PASTE_DISABLE = "\x1b[?2004l"  # JSONL 输出块结束标记
+
+type ReportEvent = dict[str, Any]  # 单条上报事件
+
+
+def _utc_now() -> str:
+    "_utc_now() 当前 UTC 时间的 ISO8601 字符串"
+    return datetime.now(timezone.utc).isoformat()
+
+
+class StatusReporter:
+    """StatusReporter 把生成的图与 Agent 实时状态以 JSONL 上报到 stdout。"""
+
+    # 类级写锁：不同实例（例如并发子 Agent 各自创建的实例）写出互不交错
+    _write_lock = threading.Lock()
+
+    def __init__(self, stream: TextIO | None = None, *,
+                 enabled: bool = True) -> None:
+        self.stream: TextIO = sys.stdout if stream is None else stream
+        self.enabled = enabled
+
+    def emit(self, events: Iterable[ReportEvent]) -> None:
+        """emit() 把一批事件序列化为 JSONL，整体包裹起止标记后写出到 stdout。"""
+        if not self.enabled:
+            return
+        payload = "".join(
+            json.dumps(event, ensure_ascii=False, default=str) + "\n"
+            for event in events)
+        if not payload:
+            return
+        with StatusReporter._write_lock:
+            try:
+                self.stream.write(BRACKETED_PASTE_ENABLE)
+                self.stream.write(payload)
+                self.stream.write(BRACKETED_PASTE_DISABLE)
+                self.stream.flush()
+            except Exception:
+                # 状态上报不得干扰工作流执行（如管道关闭时的 BrokenPipe）。
+                pass
+
+    def bind(self, status: AgentStatusSingleAgent) -> None:
+        """bind() 订阅单个 Agent 状态对象：之后每次状态变化都会自动上报。"""
+        status.on_update = self.report_agent
+        self.report_agent(status)  # 先上报一次初始 waiting 状态
+
+    def report_agent(self, status: AgentStatusSingleAgent) -> None:
+        """report_agent() 上报一次子 Agent 的当前完整快照。"""
+        self.emit([{
+            "type": "agent",
+            "time": _utc_now(),
+            "prompt": status.prompt,
+            "path": status.path,
+            "state": status.status.value,
+            "sessionId": status.session_id,
+            "nodeId": status.node_id,
+            "callIndex": status.call_index,
+            "agentIndex": status.agent_index,
+            "agentCount": status.agent_count,
+            "attempt": status.attempt,
+            "tools": [dict(tool) for tool in list(status.tool_calls)],
+        }])
+
+    def report_node(self, workflow_id: str, node_id: str, state: str,
+                    args: dict[str, Any], *, cached: bool = False) -> None:
+        """report_node() 上报节点状态变更（含全部已填充参数）。"""
+        self.emit([{
+            "type": "node",
+            "time": _utc_now(),
+            "workflow": workflow_id,
+            "nodeId": node_id,
+            "state": state,
+            "cached": cached,
+            "args": dict(args),
+        }])
+
+    def report_agents_start(self, workflow_id: str, node_id: str,
+                            call_index: int, agents: Any) -> None:
+        """report_agents_start() 在节点即将启动 Agent/MultiAgent 前上报。
+
+        ``agents`` 为 Agent 或 MultiAgent（鸭子类型，取其 prompt(s)）。
+        """
+        prompts: list[str] = []
+        single = getattr(agents, "prompt", None)
+        if isinstance(single, str):
+            prompts.append(single)
+        group = getattr(agents, "agents", None)
+        if isinstance(group, (list, tuple)):
+            for item in group:
+                value = getattr(item, "prompt", None)
+                if isinstance(value, str):
+                    prompts.append(value)
+        self.emit([{
+            "type": "agents_start",
+            "time": _utc_now(),
+            "workflow": workflow_id,
+            "nodeId": node_id,
+            "callIndex": call_index,
+            "count": len(prompts),
+            "prompts": prompts,
+        }])
+
+    def report_node_log(self, workflow_id: str, node_id: str,
+                        message: str) -> None:
+        """report_node_log() 把节点线程内 print 的输出转发为 node_log 事件。"""
+        self.emit([{
+            "type": "node_log",
+            "time": _utc_now(),
+            "workflow": workflow_id,
+            "nodeId": node_id,
+            "message": message,
+        }])
+
+    def report_node_code(self, workflow_id: str, node_id: str, name: str,
+                         code: str | None) -> None:
+        """report_node_code() 在节点启动时广播其源码（不可得时为 null）。"""
+        self.emit([{
+            "type": "node_code",
+            "time": _utc_now(),
+            "workflow": workflow_id,
+            "nodeId": node_id,
+            "name": name,
+            "code": code,
+        }])
+
+    def report_graph(self, workflow_id: str, graph: Graph) -> None:
+        """report_graph() 上报 Flow 生成的流程图（set 序列化为有序列表）。"""
+        self.emit([{
+            "type": "graph",
+            "time": _utc_now(),
+            "workflow": workflow_id,
+            "graph": {
+                "nodes": dict(graph["nodes"]),
+                "edges": {node_id: sorted(targets)
+                          for node_id, targets in graph["edges"].items()},
+                "start": sorted(graph["start"]),
+            },
+        }])
+
+
+def optional_reporter(enabled: bool) -> StatusReporter | None:
+    """optional_reporter() 按布尔开关创建默认 stdout 上报器，关闭时返回 None。"""
+    return StatusReporter() if enabled else None
+
+# === 节点线程 print 钩子：节点内 print 转为 node_log，其余线程照常 ===
+# 语义与真实 stdout 对齐：sep 连接多参数后追加 end；按 \n 成行推送，
+# 未成行的片段在线程结束或 flush=True 时补发为一条事件。
+
+_REAL_PRINT = print  # 替换前捕获的原始内置 print
+_NODE_PRINT_CONTEXTS: dict[int, tuple[StatusReporter, str, str]] = {}
+_NODE_PRINT_BUFFERS: dict[int, list[str]] = {}  # 每线程待续写的未成行片段
+_NODE_PRINT_LOCK = threading.Lock()
+
+
+def _node_print(*args: Any, sep: str = " ", end: str = "\n",
+                file: Any = None, flush: bool = False) -> None:
+    "_node_print() 内置 print 的替身：节点线程内转为 node_log 事件"
+    tid = threading.get_ident()
+    context = _NODE_PRINT_CONTEXTS.get(tid)
+    if context is None or (file is not None and file is not sys.stdout):
+        # 非节点线程 / 显式重定向到其他流时保持原生行为
+        _REAL_PRINT(*args, sep=sep, end=end, file=file, flush=flush)
+        return
+    reporter, workflow_id, node_id = context
+    # 与内置 print 一致：str() 逐个转换参数，用 sep 连接，末尾追加 end
+    buffer = _NODE_PRINT_BUFFERS.setdefault(tid, [])
+    buffer.append(sep.join(str(arg) for arg in args) + end)
+    data = "".join(buffer)
+    *lines, pending = data.split("\n")
+    for line in lines:
+        reporter.report_node_log(workflow_id, node_id, line)
+    buffer.clear()
+    if pending:
+        buffer.append(pending)
+    if flush and pending:
+        # flush=True：尚未成行的残段立即作为一条事件发出
+        reporter.report_node_log(workflow_id, node_id, pending)
+        buffer.clear()
+
+
+def _flush_node_print_buffer(reporter: StatusReporter, workflow_id: str,
+                             node_id: str, fragments: list[str]) -> None:
+    "_flush_node_print_buffer() 把未成行的残段补发为一条 node_log 事件"
+    text = "".join(fragments)
+    if text:
+        reporter.report_node_log(workflow_id, node_id, text)
+
+
+def bind_node_print(reporter: StatusReporter, workflow_id: str,
+                    node_id: str) -> None:
+    """bind_node_print() 注册当前线程：该线程内的 print 转为 node_log。
+
+    进程内首个注册会整体替换 ``builtins.print``；未注册线程的 print
+    原样透传，行为不变。
+    """
+    with _NODE_PRINT_LOCK:
+        if not _NODE_PRINT_CONTEXTS:
+            setattr(builtins, "print", _node_print)
+        _NODE_PRINT_CONTEXTS[threading.get_ident()] = (
+            reporter, workflow_id, node_id)
+
+
+def unbind_node_print() -> None:
+    """unbind_node_print() 解除当前线程注册；全部解除后还原内置 print。
+
+    解除前把该线程尚未成行的输出残段补发为最后一条 node_log，
+    保证 ``end=""`` 之类不完整输出不丢失。
+    """
+    tid = threading.get_ident()
+    with _NODE_PRINT_LOCK:
+        context = _NODE_PRINT_CONTEXTS.pop(tid, None)
+        fragments = _NODE_PRINT_BUFFERS.pop(tid, [])
+        if not _NODE_PRINT_CONTEXTS:
+            setattr(builtins, "print", _REAL_PRINT)
+    if context is not None:
+        _flush_node_print_buffer(context[0], context[1], context[2],
+                                 fragments)

dynworkflow/schemas.py

@@ -0,0 +1,88 @@
+"""ACP v2 客户端使用的类型化 JSON schema 定义。"""
+
+from __future__ import annotations
+
+from typing import Literal, NotRequired, TypeAlias, TypedDict
+
+
+JsonPrimitive: TypeAlias = None | bool | int | float | str
+JsonValue: TypeAlias = JsonPrimitive | list["JsonValue"] | dict[str, "JsonValue"]
+JsonObject: TypeAlias = dict[str, JsonValue]
+
+
+class JsonRpcError(TypedDict):
+    code: int
+    message: str
+    data: NotRequired[JsonValue]
+
+
+class JsonRpcMessage(TypedDict, total=False):
+    jsonrpc: Literal["2.0"]
+    id: int | str | None
+    method: str
+    params: JsonObject
+    result: JsonValue
+    error: JsonRpcError
+
+
+class ClientInfo(TypedDict):
+    name: str
+    title: NotRequired[str]
+    version: str
+
+
+class InitializeParams(TypedDict):
+    protocolVersion: int
+    capabilities: JsonObject
+    info: ClientInfo
+
+
+class InitializeResult(TypedDict):
+    protocolVersion: int
+    capabilities: JsonObject
+    info: JsonObject
+    authMethods: NotRequired[list[JsonObject]]
+
+
+class TextContentBlock(TypedDict):
+    type: Literal["text"]
+    text: str
+
+
+class SessionNewParams(TypedDict):
+    cwd: str
+    mcpServers: list[JsonObject]
+    model: NotRequired[str]
+
+
+class SessionResumeParams(SessionNewParams):
+    sessionId: str
+    replayFrom: NotRequired[JsonObject]
+
+
+class SessionResult(TypedDict):
+    sessionId: str
+
+
+class PromptParams(TypedDict):
+    sessionId: str
+    prompt: list[TextContentBlock]
+
+
+class SessionUpdate(TypedDict, total=False):
+    sessionUpdate: str
+    messageId: str
+    content: JsonValue
+    state: str
+    stopReason: str
+    toolCallId: str
+    title: str
+    kind: str
+    status: str
+    rawInput: JsonValue
+    rawOutput: JsonValue
+
+
+class SessionUpdateParams(TypedDict):
+    sessionId: str
+    update: SessionUpdate

dynworkflow-0.1.0.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.3
+Name: dynworkflow
+Version: 0.1.0
+Summary: Dynamic Workflow Library for Alkaid0
+Author: cxykevin
+Author-email: cxykevin <cxykevin@yeah.net>
+Requires-Dist: websockets>=15.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# dynworkflow
+
+`dynworkflow` 是一个 Python 3.12 库，用于编排动态工作流，工作流节点可以调用一个或多个 ACP Agent。
+
+## 安装
+
+使用项目包管理器安装：
+
+```bash
+uv sync
+```
+
+运行时依赖为 `websockets`，开发依赖包括 `pytest` 和 `mypy`。
+
+## 快速开始
+
+```python
+import dynworkflow as d
+
+flow = d.Flow(
+    "document-flow",
+    agent=d.AgentClient("ws://127.0.0.1:7433/acp?k=a"),
+)
+
+@flow.node("summarize")
+def summarize() -> d.TaskGenerator:
+    result = yield d.Agent("Summarize the documents in docs/test", path="docs/test")
+    return d.Result(result)
+
+flow.execute(summarize())
+```
+
+使用 `@flow.node(name)` 声明节点。普通节点可以返回 `None`、`Result` 或一个或多个下游 `Execute` 任务。生成器节点可以 `yield Agent` 或 `MultiAgent`，接收 Agent 结果后返回节点结果。
+
+## 公共 API
+
+- `Flow`：创建并执行工作流。
+- `Flow.node(name)`：注册节点函数。
+- `Flow.execute(*tasks)`：在当前进程中执行任务，并在所有节点结束后抛出节点异常。
+- `Flow.run(*tasks)`：在 fork 子进程中运行工作流，并监听 stdin 中的 JSONL 控制命令。
+- `Agent`：描述一次 Agent 请求。
+- `MultiAgent`：并发运行多个 Agent 请求。
+- `AgentClient`：连接 ACP WebSocket 端点。
+- `Result`：保存节点的最终结果。
+
+## 执行语义
+
+- 相互独立的节点会并发运行。
+- 节点失败后会立即变为 `error` 状态，并在启用上报时立即发送状态。
+- 失败节点不会停止兄弟节点。
+- 所有节点异常会在最后统一以 `ExceptionGroup` 抛出。
+- 节点和 Agent 的终止命令只影响指定目标；工作流关闭会终止整个工作流。
+
+## 缓存与状态上报
+
+缓存默认启用。可以使用 `Flow(..., cache=False)` 关闭缓存。缓存文件位于 `.alkaid0/workflow.db`；设置 `ALKAID0_WORKFLOW_SESSION_ID` 可以隔离不同会话。
+
+可以通过 `Flow(..., report=True)` 或环境变量 `ALKAID0_WORKFLOW_REPORT=1` 开启 JSONL 状态上报。`Flow.run()` 会自动开启上报。事件包括 `graph`、`node`、`agent`、`agents_start`、`node_code` 和 `node_log`。
+
+## 示例
+
+参见 `example.py`，其中包含使用 `AgentClient`、`Agent`、`MultiAgent`、分支和回退参数的完整工作流示例。
+
+## 测试
+
+运行测试套件：
+
+```bash
+python -m pytest -q
+```
+
+运行静态编译检查：
+
+```bash
+python -m compileall -q src tests
+```
+
+## 文档索引
+
+- `docs/SKILL.md`：仅供 AI Agent 读取的使用说明，保持英文。
+- `docs/architecture.md`：面向人的实现与生命周期说明。
+- `docs/protocol.md`：stdin 控制命令和 JSONL 上报事件说明。
+- `docs/test/ai_must_read.md`：示例工作流读取的测试文档。

dynworkflow-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+dynworkflow/__init__.py,sha256=s9TjO6XUkcAZDxJEv0s7WVP9MhGBKrHuWRpgxxmtvbY,317
+dynworkflow/agent.py,sha256=7FmxKSNYNIwljZ-IzxRgbpIhCSErXtvazEAX-JLVSjY,42600
+dynworkflow/cache.py,sha256=W9GLvLq1wMRcq0hIMVk5BO5FIuzaXcRluckvR5XQCdk,10412
+dynworkflow/flow.py,sha256=rEbm8HmZRMCLwE9_QW1_Vq2ei3JW0cXct5UlwtnRTgo,27861
+dynworkflow/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dynworkflow/reporter.py,sha256=5zX7UU0nXj1vpx2RR5R_OgLh9nROCdJUM6Wx2zVXgxQ,10277
+dynworkflow/schemas.py,sha256=-if9rPA1fDZ7wcPGK4Rr9TDOyUxS9O2xLOpPPAgtNXo,1774
+dynworkflow-0.1.0.dist-info/WHEEL,sha256=l3MmIxu8qaet7ng2J9fFoJnYGj8IREj7jXTbgsuzmy4,81
+dynworkflow-0.1.0.dist-info/METADATA,sha256=gdzAfRgWdFBMqXOD_5aVok3mBQDsUEk-ANDMPf_G6hw,3032
+dynworkflow-0.1.0.dist-info/RECORD,,

dynworkflow-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.32
+Root-Is-Purelib: true
+Tag: py3-none-any