Metadata-Version: 2.4
Name: tketool-agent-studio
Version: 1.8.0
Summary: Local visual editor for tketool Pipeline Graphs
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: filelock<4,>=3.32.5
Provides-Extra: runtime
Requires-Dist: tketool.pipeline==1.7.1; extra == "runtime"

# Pipeline Studio

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

## 本地开发

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

```bash
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 通过标准输入调用：

```bash
python -m tketool.pipeline
```

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

## 打包与命令

```bash
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 不一致时返回冲突。项目文件、示例和运行数据不会被清理或迁移。

## 验证

```bash
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 不拥有任何示例的执行代码。

参见 [架构说明](docs/architecture.md)。


## 项目管理与调试

画布顶部的项目管理入口在单项目和全局模式均可用。可打开已有目录、在空目录新建基础 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`。

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

```json
{"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 组件源码。旧版本定义不会隐式迁移。
