SuperAPI AI 工具集

kitaru-authoring

通用与其它

查看项目

更新于 10-16 07:20

技能介绍

用途:指导编写或重构 Kitaru 持久化工作流,并选择合适接口来运行、观测、重放、控制、部署和检查持久化产物与外部状态引用。若工作流形态尚不清晰,建议先用 kitaru-scoping 技能确定 Kitaru 是否适用、检查点与等待位置、应显式化的产物及稳定重放锚点。

核心模型:@flow 是持久化外层边界;@checkpoint 是流内重放边界;wait() 在流级别暂停并稍后带输入恢复;重放从头重跑,但所选重放点之前的检查点返回缓存输出;artifact 是绑定到某次执行或检查点的命名产物。流通过 .run(...) 执行,不能直接调用被装饰函数。FlowHandle 提供 exec_id、status、wait()、get()。

编写约束:不得嵌套 flow;不得在 checkpoint 内调用另一 checkpoint;不得在 checkpoint 内调用 wait();save()/load() 需 checkpoint 作用域;log() 在两种作用域均可但元数据挂载目标不同;checkpoint 输出必须可序列化;.submit()/.map()/.product() 用于运行中流内启动的工作;llm() 仅在 @flow 内有效,在 checkpoint 外会自动生成合成 llm_call 检查点;检查点、等待、产物应使用稳定唯一名称。

原语:@flow 支持 stack、image、cache、retries 覆盖,入口为 .run(...) 与 .replay(exec_id, from_=..., overrides=..., **flow_inputs);current_execution_id() 在运行中返回执行 ID,否则为 None。@checkpoint 支持 retries、type、cache,可被直接调用或经 .submit/.map/.product。wait(*, schema=bool, name=None, question=None, timeout=None, metadata=None) 仅在流体内有效,默认超时 600 秒(轮询窗口,执行仍保持等待)。log(**kwargs) 记录结构化元数据。save(name, value, *, type="output", tags=None) 与 load(exec_id, name) 需检查点作用域,产物类型限 prompt、response、context、input、output、blob。llm(prompt, *, model=None, system=None, temperature=None, max_tokens=None, name=None) 仅在 @flow 内有效,仅它自动解析别名关联密钥。

跨执行状态:当前公开接口不含原生键值状态 API,需用 save(...) 保存执行关联值、传递上游执行 ID,或把全局配置存入外部数据库、对象存储、仓库文件或服务 API;敏感配置用 Kitaru secrets。

重放与控制:重放入口有 SDK flow.replay、KitaruClient().executions.replay、CLI kitaru executions replay <exec_id> --from <selector> [--override checkpoint.<name>=<value>]、MCP kitaru_executions_replay。from_ 指向检查点选择器,等待选择器不可作重放锚点;覆盖键须用 checkpoint.<selector> 命名空间,不支持 wait.* 覆盖。等待解析:用 client.executions.input、CLI kitaru executions input 或 MCP kitaru_executions_input 提供输入;abort_wait 中止;必要时用 resume 手动恢复。

接口差异:SDK 用于编写与启动执行;KitaruClient 用于管理已有执行与检查产物,不能启动新执行;CLI 提供 login、stack、secrets、executions、deploy 等命令;MCP 提供 kitaru_executions_、kitaru_deployments_、kitaru_artifacts_* 等工具。远程栈创建仅 CLI/MCP 支持,SDK create_stack() 仅本地栈。

适配器:PydanticAI 用 KitaruAgent 与 CapturePolicy;OpenAI Agents 用 KitaruRunner,checkpoint_strategy 可选 runner_call 或 calls;LangGraph 用 KitaruGraphRunner,默认 graph_call。wrap(...) 仅为已弃用兼容层,不应作为新代码常规路径。具体细节以官方文档为准,资料未提供处暂未说明。