Pipeline Studio

Pipeline Studio 是本地的 tketool.pipeline Graph 可视化编辑器。Pipeline Python 包拥有 GraphDefinition、组件 registry、类型分析、校验和 YAML 渲染语义；Studio 只消费这些公开契约并编辑 Graph 数据，不维护内置节点、边或类型规则的副本。

本地开发

需要 Node.js >= 22.13 和 Python >= 3.11：

pnpm install --frozen-lockfile
pnpm dev

默认页面为 http://localhost:3000，API 为 http://127.0.0.1:3210。可用 AGENT_STUDIO_PROJECT=/absolute/project 固定单项目目录。独立端口启动时设置 AGENT_STUDIO_API_PORT、AGENT_STUDIO_WEB_ORIGIN 和前端的 VITE_AGENT_STUDIO_API_ORIGIN。

项目应包含 graph.yaml、graph/agent.yaml 或 graphs/*.yaml。Graph 使用 version 3；自定义 registry 与模型类型通过 module:symbol 引用。项目 Python 必须能导入该项目声明的模块和兼容的 tketool.pipeline。

Studio 通过标准输入调用：

python -m tketool.pipeline

请求 action 为 catalog、inspect 或 render。读取和编辑界面展示返回的 node/edge catalog、JSON Schema、类型分析与 diagnostics；保存只接受 Pipeline render 返回的 YAML，并使用文件 revision 拒绝外部并发修改。

打包与命令

pnpm build:package
python3 -m pip install .
tketool-agent-studio open /absolute/project

安装后的 CLI 使用用户级单例本地服务。status 查看状态，stop 关闭服务；重复 open 会复用服务。--python /project/.venv/bin/python 指定项目解释器。CLI 不初始化项目、不安装项目依赖，也不执行 Graph。

基础包只依赖 filelock；.[runtime] 可安装当前声明的 Pipeline 版本作为缺省解释器环境。Node.js 是运行 Web 服务的显式前置条件。

安全边界

服务只监听 loopback，校验 Host 和精确 Origin，修改请求需要 x-agent-studio: local。Graph 路径必须位于项目根目录内。保存使用同目录临时文件加原子 rename，并在 revision 不一致时返回冲突。项目文件、示例和运行数据不会被清理或迁移。

验证

pnpm typecheck
pnpm lint
pnpm test:server
pnpm build
pytest -q tests/unit/test_package_cli.py

安装包生命周期测试需先构建并安装 wheel，然后设置 STUDIO_TEST_CLI 和 STUDIO_TEST_NODE 运行 tests/e2e/test_package_launch.py。

examples/samplegraph 与 examples/all_node_provenance 是保留的 Pipeline v2 历史实例，需要显式升级为 Graph v3 后才能由当前 Studio 编辑。当前 v3 registry 示例位于仓库的 ../../examples/pipeline/registered_agent；Studio 不拥有任何示例的执行代码。

参见 架构说明。

项目管理与调试

画布顶部的项目管理入口在单项目和全局模式均可用。可打开已有目录、在空目录新建基础 Graph、修改项目名称或 Python 解释器、从最近项目移出条目。移出不删除磁盘文件。新建使用 Pipeline 提供的默认 Graph，拒绝覆盖非空目录；若文件创建后登记失败，错误提示会引导改用打开项目恢复。

画布工具栏可切换组件库、配置面板与缩略图。Node/Edge 的标题、用途及图标优先读取 Pipeline 的 display 元数据；配置说明来自公开 Schema。

画布自动展示虚拟“开始”和“结束”标记，按 flow.start / flow.end（支持多个出口）连接真实节点；工具栏可定位边界。标记不进入 Graph YAML 或 layout。拖动左右分隔条可调整组件库、配置面板宽度；底部横向分隔条可调整 Debug/诊断区高度。分隔条也支持方向键，尺寸保存在当前浏览器。

组件库只列节点与类型。连线通过“添加连线”或从节点右侧端口拖到目标左侧端口创建，并显式选择注册类型。选中已有连线后可拖动端点改接，或在配置面板修改起点、终点、类型和参数；删除按钮与 Delete 键均可删除连线。改接保留原连线参数及显示元数据。结构在调试期间锁定，停止后恢复编辑；保存仍由 Pipeline 校验，拒绝重复连线等无效结构。

Debug 支持启动、单步、继续、停止和事件输出检查。必须先保存有效 Graph；启动会校验 revision，并以同一版本快照加载。单步在公开 NodeEvent 返回后暂停，不是 Python 行断点。Session 输入留空时不传上下文。没有外部依赖的 Graph 可直接运行；需要资源的项目通过 .pipeline-studio/debug.json 显式配置 factory，由 factory 返回 GraphEnvironment。

新事件到达后，画布自动高亮并定位当前节点，执行轨迹和输出同步跟随；点击历史事件可检查此前结果。

{"version": 1, "factory": "debug_adapter:make_debug_runtime", "allowedModules": ["my_project"]}

factory 是项目代码，接收 project_root, graph_path, run_id, input, session，返回可选 environment（GraphEnvironment）、dependencies（自定义组件依赖）、context、config。graph_path 是只读临时 Graph 快照，资源配置应基于 project_root。这些运行对象留在项目 Python 子进程。打包后 Studio 通过随附脚本调用项目解释器，不要求该解释器安装 Studio 包。

完整示例见 ../../examples/pipeline/all_components_demo。该例使用本地测试 PromptPool/Memory，未访问真实模型或数据库。

Pipeline 1.7.1 配置编辑

默认运行时固定为 PyPI tketool.pipeline==1.7.1。开发启动前可执行 npm run setup:runtime 准备 Studio 自有环境；已有项目仍使用其选择的 Python 解释器，需要自行安装兼容的 Pipeline。只有显式设置 AGENT_STUDIO_PIPELINE_SOURCE=1 才使用仓库 Pipeline 源码进行联调。

加载项目后，右侧「Graph 设置」按 definitionSchema 展示类型声明、Pipeline 属性及入口/出口；选择 Node 或 Edge 后，按对应注册类型的 configSchema 显示参数、默认值、约束及帮助，嵌套对象可展开字段编辑。节点执行策略和画布显示也读取定义 schema。映射、数组及多类型值通过 JSON 输入编辑。恢复默认会删除该字段的显式覆盖。

修改类型声明或注册表后点击「Pipeline 校验」刷新组件及类型目录；点击「保存 Graph」由 Pipeline 校验并回写原 Graph YAML，再次读取可继续编辑。Studio 的修改不会直接改写 Python 组件源码。旧版本定义不会隐式迁移。