Metadata-Version: 2.5
Name: runcanvas
Version: 0.1.0
Summary: A local architecture canvas driven by real Python execution
Requires-Python: >=3.11
Requires-Dist: fastapi<1,>=0.135
Requires-Dist: httpx<1,>=0.28
Requires-Dist: platformdirs<5,>=4
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: uvicorn<1,>=0.34
Provides-Extra: server
Requires-Dist: fastapi<1,>=0.135; extra == 'server'
Requires-Dist: uvicorn<1,>=0.34; extra == 'server'
Description-Content-Type: text/markdown

# RunCanvas

用真实 Python 执行事件驱动的本地项目架构画布。完整图提供背景，每一次业务操作拥有独立任务、执行轨迹和历史回放。

首版：Python 3.11+，同步 / asyncio，分支、结构化并行、循环重试、错误与取消。业务代码负责执行，RunCanvas 负责观察。

## pip 安装与启用开关

要求 Python 3.11+。发布到 PyPI 后可直接 `pip install runcanvas`。
发布前可安装本地 wheel：`pip install ./dist/runcanvas-0.1.0-py3-none-any.whl`。
普通安装已包含 SDK、本地服务和前端，无需 Node.js、Docker 或云账号。

```python
rc = RunCanvas("my-project", graph, enabled=True)
```

`enabled=True`（默认）自动启动或复用本地服务，并打开 `http://127.0.0.1:7331`。
改为 `enabled=False` 后，不创建上报线程、不启动服务、不打开浏览器、不记录事件，业务照常执行。
这是初始化配置，调整后重新创建客户端；禁用不删除历史、不停止其他客户端使用的服务。

- `open_browser=False`：仍采集并启动服务，只是不自动打开浏览器。
- `auto_start=False`：由你管理服务，SDK 只上报。
- `endpoint="http://127.0.0.1:7340"`：使用另一个本地端口。

自动启动的服务随 Python 进程退出。短脚本结束后，或需要独立查看服务时：

```bash
runcanvas serve --open
```

可以查看已保存的历史和运行示例，按 Ctrl+C 停止服务。业务程序退出前调用 `rc.close()` 排空事件；
关闭客户端不会停止共享服务。发布步骤见 [PyPI 发布指南](docs/publishing.md)。

## 开发启动

```powershell
uv sync --extra server
cd web
npm ci
npm run build
cd ..
uv run runcanvas serve
```

打开 **http://127.0.0.1:7331**。点击「运行示例」触发真实文件处理任务。Node.js 仅在开发 / 打包前端时需要。

## 接入自己的项目

```python
from runcanvas import Graph, Node, Edge, RunCanvas

graph = Graph(
    id="hello", title="我的第一个流程",
    nodes=[Node(id="START", label="开始"), Node(id="greet", label="生成问候"), Node(id="END", label="结束")],
    edges=[Edge(id="enter", source="START", target="greet"), Edge(id="exit", source="greet", target="END")],
)
rc = RunCanvas("my-project", graph)

@rc.node("greet")
def greet(name: str) -> str:
    return f"Hello, {name}!"

with rc.task("第一次问候"):
    print(greet("RunCanvas"))

rc.close()  # 脚本退出前，最多等待 3 秒排空事件
```

启用时会自动准备本地服务（首次启动最多等待约 5 秒）；服务不可用时记录警告，业务仍正常执行。完整文档见 [快速开始](docs/quickstart.md)、[SDK API](docs/api.md)、[图与事件契约](docs/protocol.md)、[AI 接入指南](docs/ai-integration.md)。

## 检查与交付

```powershell
uv run pytest
uv run ruff check .
cd web
npm run check
npm test
npm run build
npm run test:e2e
cd ..
uv build
```

构建 wheel 前必须执行前端构建，wheel 内包含静态界面。普通安装已包含服务依赖，`server` extra 保留兼容。

数据存储于系统用户应用数据目录（Windows 默认 `%LOCALAPPDATA%\RunCanvas`），可通过 `--data-dir` 修改。默认只监听本机；历史保留直到执行 `runcanvas clean --yes`。

观测暂不跨进程、跨请求或自动跨线程；前端交互与外部服务内部状态不自动采集。默认不记录函数输入输出。断连使用内存缓冲，进程强制退出时未确认的事件可能丢失，界面将观测新鲜度与业务结果分开显示。
