plaita-nodes

plaita 的通用节点集（infra 级）：把 plaita 声明式流程接到真实世界——Agent CLI、本地命令、微信人工确认、通知、文件。

背景：ADR-2026-08-27 编排双轨收敛 ——编排内核收敛到 plaita，Agent 执行层统一走 agentproc；本仓是这层决议的节点承载。

节点一览

节点经 pyproject 的 [project.entry-points."plaita.nodes"] 自动注册；plaita_nodes.register_all() 可手动注册。

原子节点设计原则

抽象一条硬标准——原子性（一个节点只做一件不可再分的事）、通用性 （不绑定业务语义与特定凭证）、普适性（覆盖一类外部交互）：

• Agent ≠ LLM：agentrun 是多步工具循环的 Agent 原子（重）；llm 是单次 补全的 LLM 原子（轻）。流程里"摘要/改写/抽取/分类"用 llm，"多步编码/ 工具任务"用 agentrun。
• 决策 ≠ 生成：decision 是单步、封闭决策空间的判断原子（路由/分类/ 打分），输出类型化决策 + 置信度，choice 必落在决策空间内；开放文本生成 归 llm。理念对标 System One 决策模型（如 TypeSafe Jev）——流程里 "该走哪个分支"用 decision，"写一段话"用 llm。
• 纯文本变换（判决提取、frontmatter 解析等）不做节点——注册为表达式 F.* 函数（ExpressionRegistry.register），在 assignment 里一行使用。
• 业务领域的状态机（如内容池销账）属于业务仓，不放本仓。

快速上手

# monorepo 内可编辑安装（plaita / agentproc 均为兄弟仓）
pip install -e ../plaita[http] -e ../agentproc/sdk/python -e .

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 + 模板表达式）：

{
  "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 加映射，本仓节点无需改动。

开发

pip install -e ".[dev]"
pytest