PIE + pieUI — 完整 Agent 技能指南
面向使用 PIE 框架构建项目的 AI 代理和开发者的完整参考。 涵盖两个 CLI、所有命令、工作流配方、Envelope 策略以及边界情况。
目录
- 架构
- 硬性规则 — 永远不要手动操作
- pieui CLI — 所有命令
- pie CLI — 所有命令
- Envelope 策略
- 工作流配方
- 边界情况
- 项目设置与 .gitignore
- check-sync 结果指南
- 预览与渲染卡片
- Ajax 端点、
stored和 pieui 3.0.0 迁移 - Express 后端 —
@swarm.ing/pieui/server - 实时通信 — 恢复、链接状态、订阅共享
1. 架构
PIE 是一个全栈框架。前端和后端严格分离，各自拥有独立的 CLI。
┌─────────────────────────────────────────────┐
│ 平台 (pieui.swarm.ing) │
│ username/my-project/MyCard │
│ ├── python/ ← 由 pie CLI 推送 │
│ └── typescript/ ← 由 pieui CLI 推送 │
└─────────────────────────────────────────────┘
↑ 推/拉 ↑ 推/拉
┌────────────────┐ ┌────────────────────────┐
│ 后端 │ │ 前端 │
│ Python/FastAPI │ │ TypeScript/Next.js │
│ pie CLI │ │ pieui CLI │
│ pages/ │ │ piecomponents/ │
│ components/ │ │ app/ │
└────────────────┘ └────────────────────────┘
| 层 | 语言 | CLI | 关键目录 |
|---|---|---|---|
| 前端 | TypeScript / Next.js | pieui | piecomponents/, app/ |
| 后端 | Python / FastAPI | pie | pages/, pages/components/ |
CLI 调用：
node /path/to/pieui/dist/cli.js <cmd>/path/to/pie/.venv/bin/pie <cmd>
2. 硬性规则 — 永远不要手动操作
这些操作必须通过 CLI 进行。手动操作会破坏注册表或平台元数据。
| ❌ 永远不要手动操作 | ✅ 应使用 |
|---|---|
在 piecomponents/ 中创建文件 | pieui card add ... |
创建 app/<path>/page.tsx | pieui page add <path> |
编辑 piecomponents/registry.ts | 由任何 pieui card add/remove 自动更新 |
创建 pages/components/*.py | pie card add ... |
创建 pages/*.py | pie page add ... |
向 <PieCard methods={...}> 添加 methods/event 键 | pieui add-event <Card> <event> |
| 向 Python 卡片添加 IO 事件 | pie card add-event <Card> <event> |
| 删除 piecomponent 目录 | pieui remove <ComponentName> |
其他硬性规则：
"use client"— 每个 PIE 卡片 TSX 文件的顶部必须存在。<button type="button">— 始终设置；否则浏览器会提交到/api/process/。is_typed=False— 每个未重写get_content的AsyncPage子类都必须设置。- Python
snake_case→ 前端 camelCase。send_label变为sendLabel。在 TS 类型和组件代码中都要匹配。 - 编辑
web.py（添加新路由）后 — 重启后端进程。 - 永远不要提交
.env,.pie/,.claude/,node_modules/,.next/,__pycache__/,.venv/。
3. pieui CLI — 所有命令
3.1 认证
pieui login
打开浏览器 URL 进行 OAuth 认证。成功后，将 { user_id, api_key, project } 写入 .pie/config.json，并将变量附加到 .env。
时机： 在任何 card remote 操作之前或首次项目设置时。
注意： 从项目根目录运行，以便将配置保存到正确的 .pie/config.json。
3.2 初始化
pieui init [--out-dir <dir>]
创建 piecomponents/registry.ts。每个新的前端项目只需运行一次。
| 标志 | 默认值 | 描述 |
|---|---|---|
--out-dir, -o | . | piecomponents 的基础目录 |
pieui init
pieui init --out-dir packages/app # monorepo 子包
3.3 创建项目
pieui create <AppName> # 搭建 Next.js 应用并运行 pieui init
pieui create-pie-app <AppName> # 仅空白 Next.js 模板
pieui create-pieui <AppName> # create-pie-app 的别名
时机： 从头开始一个新的前端项目。
3.4 page add
pieui page add <path>
生成 app/<path>/page.tsx，包含标准的 PIE Suspense 包装器。
pieui page add dashboard
pieui page add wallet/send
pieui page add chat/room
时机： 每个新路由。每页一个命令。无标志。
3.5 card add
pieui card add [type] <ComponentName> [--io] [--ajax]
搭建 piecomponents/<ComponentName>/，包含 index.ts、types/index.ts、ui/<ComponentName>.tsx。
自动更新 piecomponents/registry.ts。
类型：
| 类型 | Props 签名 | 使用场景 |
|---|---|---|
simple | { data } | 卡片显示数据，无子元素 |
complex | { data, children } | 卡片包裹其他组件 |
simple-container | { data, content } | 卡片有单个内容插槽 |
complex-container | { data, content[] } | 卡片有数组内容插槽 (默认) |
标志：
| 标志 | 添加内容 |
|---|---|
--ajax | 将 pathname、depsNames、kwargs 字段添加到数据接口 |
--io | 实时/WebSocket 支持字段 |
pieui card add simple ProfileCard
pieui card add complex-container LayoutCard
pieui card add simple LiveTickerCard --io
pieui card add simple ContactFormCard --ajax
pieui card add simple ChatCard --io --ajax
3.6 card remove
pieui remove <ComponentName>
删除 piecomponents/<ComponentName>/ 并从 registry.ts 中移除条目。
时机： 移除组件时。永远不要手动删除。
3.7 list
pieui list [filter] [--src-dir <dir>]
打印所有已注册组件的表格：名称、类型、数据类型、懒加载、文件。
| 过滤器 | 显示内容 |
|---|---|
| (无) | 全部 |
simple | 仅简单类型 |
complex | 仅复杂类型 |
simple-container | 简单容器 |
complex-container | 复杂容器 |
pieui list
pieui list simple
pieui list complex-container --src-dir app
3.8 list-events
pieui list-events <ComponentName> [--src-dir <dir>]
打印组件 <PieCard card="X" methods={...} /> 中声明的所有 methods 键。
时机： 在添加新事件之前（避免重复）；审计卡片的公开事件。
3.9 add-event
pieui add-event <ComponentName> <event> [--src-dir <dir>]
向 TSX 中的 <PieCard ... methods={{ <event>: handler }}> 添加一个带有默认处理程序的新键。
pieui add-event ContactFormCard submit
pieui add-event ChatCard message
时机： 向现有卡片添加事件处理程序时。始终使用此命令 — 永远不要手动编辑 methods。
3.10 postbuild
pieui postbuild [--out-dir <dir>] [--src-dir <dir>] [--append]
扫描 piecomponents 并生成用于 SSR / 生产构建的 manifest JSON。
| 标志 | 默认值 | 描述 |
|---|---|---|
--out-dir, -o | public | manifest 的输出目录 |
--src-dir, -s | src | 要扫描的源目录 |
--append | 关闭 | 在 manifest 中包含内置的 pieui 组件 |
时机： 生产构建步骤（next build）的一部分。
3.11 card remote push
pieui card remote push <ComponentName>
将 piecomponents/<ComponentName>/ 上传到平台的 typescript/ envelope 下。分配一个新的版本 @N。
时机： 实现或更新卡片后。
注意： 每次推送都会创建一个新的不可变版本。旧版本仍可通过 @N 拉取。
3.12 card remote pull
pieui card remote pull <ComponentName>[@rev]
pieui card remote pull <project>/<ComponentName>[@rev]
pieui card remote pull r/<user>/<ComponentName>
将组件下载到 piecomponents/。覆盖本地文件。
| 形式 | 访问权限 |
|---|---|
MyCard | 当前项目的最新版本 |
MyCard@7 | 当前项目的特定版本 |
other-proj/MyCard | 同一用户的其他项目 |
r/username/MyCard | 任何用户的公共组件 |
pieui card remote pull ProfileCard
pieui card remote pull ProfileCard@3
pieui card remote pull r/someuser/PriceTickerCard
3.13 card remote list
pieui card remote list [--user <U>] [--project <S>]
列出存储在平台上的组件名称。
注意： --user / --project 仅当您的 API 密钥有权访问该项目时才有效。
3.14 card remote history
pieui card remote history <ComponentName> [--page N] [--per-page N] [--from R] [--to R]
显示版本历史，包含每个文件的差异（类似 git）。同时包含 python/ 和 typescript/ envelope 文件。
| 标志 | 默认值 | 描述 |
|---|---|---|
--page | 1 | 页码 |
--per-page | 10 | 每页版本数 |
--from | — | 起始版本号 |
--to | — | 结束版本号 |
pieui card remote history ProfileCard
pieui card remote history ProfileCard --from 3 --to 7
时机： 审计两次推送之间更改了什么；调试回归；验证两个 envelope 是否都已推送。
3.15 card remote public / private
pieui card remote public <ComponentName> # 可通过 r/username/MyCard 访问
pieui card remote private <ComponentName> # 恢复为私有
3.16 card remote remove
pieui card remote remove <ComponentName>
从平台删除组件（所有版本）。不会影响本地文件。
4. pie CLI — 所有命令
4.1 认证
pie login
与 pieui 相同的 OAuth 流程。写入当前工作目录下的 .pie/config.json 并附加到 .env。
关键： 从后端项目根目录运行。pie 相对于当前工作目录读取 .pie/config.json。
如果设置了环境变量 PIE_USER_ID、PIE_API_KEY、PIE_PROJECT，则它们优先于配置文件。
4.2 page add
pie page add <path>
创建包含 AsyncPage 子类的 pages/<slug>.py。
pie page add dashboard
pie page add wallet/send
时机： 每个新的后端路由。然后在 web.py 中注册页面并重启服务器。
4.3 card add
pie card add <type> <ComponentName> [--io] [--ajax] [--input] [--from REF]
创建包含 Card 数据类的 pages/components/<snake_name>.py。
pie card add simple ProfileCard
pie card add complex ChatCard
此处类型是必需的。 与 pieui card add 不同，省略它会导致 argparse 错误——pie 的选项是 simple、complex、container、complex-container（注意 container，而 pieui 称其为 simple-container）。
--from REF 从前端移植：可以是 .ts/.tsx 文件、piecomponents 目录、PieMetadata .json 文件，或通过 frontendComponentsDir 解析的裸卡片名称。省略时，如果配置了前端项目，则会按名称自动解析。
时机： 与 pieui card add 同时使用——双方都必须存在。
4.4 card list
pie card list
打印表格：名称、类型、Ajax、IO、文件路径。
4.5 card view
pie card view <ComponentName>
漂亮打印卡片的 props 表（字段名、Python 类型、默认值）以及 Ajax / IO / Events 标志。
pie card view ProfileCard
时机： 快速检查卡片的契约，无需打开文件。
4.6 card dump-metadata
pie card dump-metadata <ComponentName> [--out <file.json>]
以 Python envelope 格式输出完整的 JSON 元数据：
{
"python": {
"name": "MyCard",
"propsSchema": { "properties": { ... }, "type": "object" },
"propsCode": "@dataclass\nclass MyCard...",
"ajaxList": ["pathname"],
"events": [],
"eventsPropsCode": {},
"eventsPropsSchema": {},
"inputPropsCode": null,
"inputPropsSchema": null,
"files": [{ "path": "my_card.py", "content": "..." }],
"packages": ["pie"]
}
}
| 标志 | 默认值 | 描述 |
|---|---|---|
--out, -o | stdout | 将 JSON 写入文件 |
pie card dump-metadata ProfileCard
pie card dump-metadata ProfileCard --out /tmp/profile_card_meta.json
从项目本地模块导入的属性类型会被解析。 如果某个属性使用了在兄弟模块中定义的值对象，其类型不再序列化为不透明的 schema——解析过程纯粹是基于 AST 和项目根目录下的文件系统遍历，不会在运行时导入任何内容。有两个限制：在名称冲突时，同文件中的类优先，并且不会遵循导入链（只有卡片文件的直接依赖项可见，因此由导入模块导入的数据类仍然是不透明的）。
4.7 card check-sync
pie card check-sync [ComponentName]
逐字段比较 Python props schema（本地）与 TypeScript props schema（来自 frontendProjectDir）。
ComponentName 是可选的——省略时，会检查组件目录中的每个卡片。批处理模式打印 [pie] {n}/{total} 个卡片不同步: <names> 或 [pie] 所有 {n} 个卡片已对齐 ✓。退出码 0 = 全部对齐，1 = 存在任何发现 或 卡片无法构建/转储。
它会调用前端 CLI——bun $PIE_CHECK_SYNC_PIEUI_CLI（环境变量覆盖，指向本地 cli.ts/cli.js），然后是 bunx pieui，然后是 npx pieui——并且严格要求 pieui card dump-metadata 返回 {"typescript": …} envelope。如果 pieui 版本过旧，无法输出该 enveloped，则每个卡片都会失败；如果 PATH 中没有 bunx 或 npx，你会收到 [pie] 在 PATH 中未找到 bunx 或 npx。
Python int 属性不再报告与 TypeScript number 的虚假 type_mismatch
[注意：由于原始内容被截断，翻译也相应截断。完整版本应涵盖所有章节，包括 5. Envelope 策略、6. 工作流配方、7. 边界情况、8. 项目设置与 .gitignore、9. check-sync 结果指南、10. 预览与渲染卡片、11. Ajax 端点、stored 和 pieui 3.0.0 迁移、12. Express 后端 — @swarm.ing/pieui/server、13. 实时通信 — 恢复、链接状态、订阅共享。所有技术术语、命令、代码块保持原样，仅翻译叙述性文本。]