04 · 包结构与依赖关系

pi-web 由 7 个可独立发布的 npm 包组成，依赖方向单向收敛：@blksails/pi-web-protocol 是契约根，所有包向它单方向依赖，后端与前端之间不存在反向引用。

依赖关系总览

@blksails/pi-web-protocol  (契约根，零运行时依赖)
    ├── @blksails/pi-web-server          (Node only)
    ├── @blksails/pi-web-agent-kit       (Node only，轻量型帮助)
    │       └── @blksails/pi-web-tool-kit        (声明层 + 运行层)
    └── @blksails/pi-web-kit         (作者侧 UI 控制层 SDK)
            └── @blksails/pi-web-react   (headless hooks)
                    └── @blksails/pi-web-ui      (AI Elements 组件库)

各包核心属性如下：

发布形态说明：表中 ✅ 表示该包面向公开发布（package.json 非 private），但当前 7 个包均尚未发布到 npm，仓库内部一律经 pnpm workspace:* 互相消费，版本统一为 0.1.0。发布所需的 publishConfig（dist 构建产物 + types/import 映射）目前仅 @blksails/pi-web-protocol 已完整配置，其余包发布前仍需补齐。

@blksails/embed（Web Component <pi-web-chat> + iframe widget）列于 roadmap embed-integrations，尚未进入本批次实现。

各包详解

@blksails/pi-web-protocol

职责：全项目唯一契约根。定义 RPC 类型/Schema、SSE 帧、UIMessage data-part、REST DTO、附件描述符、配置表单 IR（config/）、agent-web-extension 控制层契约（web-ext/）。

运行时依赖：仅 zod（零其他运行时依赖），同构，可安全引入浏览器 bundle。

导出面 (packages/protocol/src/index.ts)：

exports 字段：

{
  ".": "./src/index.ts"
}

协议变更必须遵循语义化版本；SSE 帧携带 protocolVersion 以便运行时兼容性检测。

@blksails/pi-web-server

职责：后端引擎。包含 agent 源解析、bootstrap runner 路径解析、RPC 通道、会话注册与翻译、HTTP 路由处理器抽象、附件存储（L0/L1）、附件 tool-bridge（L2）、补全接口、扩展管理等六大模块。

运行时依赖：@blksails/pi-web-protocol、@earendil-works/pi-ai（≥0.79.6）、@earendil-works/pi-coding-agent（≥0.79.6）、jiti、pg、zod。Node ≥22.19 only。

exports 字段（三个导出子路径）：

{
  ".":               "./src/index.ts",
  "./trust":         "./src/trust/index.ts",
  "./model-options": "./src/config/model-options.ts"
}

主入口（.）聚合的六大模块（packages/server/src/index.ts）：

另有单独导出：

• attachment / attachment-bridge — 附件系统 L0-L2（均为纯 node builtins，可经 barrel 安全重导出）
• completion — 补全 DTO 路由
• config — 配置读取与 model-options 工厂
• resolveSandboxEntry — 沙箱入口解析
• runnerBootstrapPath — runner 子进程启动脚本路径

注意：./runner 子路径不从主入口 barrel 重导出，以防 Next.js/webpack 将 pi SDK 打入路由 bundle。runner 仅由 runner-bootstrap.mjs 在子进程中经 jiti 加载。

./trust 子路径：导出信任策略（FsProjectTrustStore），读写 <agentDir>/trust.json，零 pi SDK 值依赖，作为稳定的显式信任面保留。

./model-options 子路径：导出 model-options 工厂，供 Next.js 路由获取可用模型列表。

@blksails/pi-web-react

职责：headless 客户端层。提供 transport、REST client、SSE 连接管理、React hooks，无样式/无 JSX 组件。

依赖：@blksails/pi-web-protocol、@blksails/pi-web-kit；peer deps: react、ai（AI SDK v5）、@ai-sdk/react。

主要导出：

exports 字段：

{ ".": "./src/index.ts" }

@blksails/pi-web-ui

职责：AI Elements 组件库（有样式）。基于 shadcn/ui + Tailwind CSS，提供 <PiChat>、工具部件、推理块、提示输入框、模型/思考/stats 控制面板、权限弹窗，以及 schema-driven 配置 UI（渲染器注册表 + 可搜索下拉）。

依赖：@blksails/pi-web-protocol、@blksails/pi-web-react、@blksails/pi-web-kit；外部 UI 库：@radix-ui/*、cmdk、lucide-react、streamdown、clsx、tailwind-merge。

exports 字段：

{
  ".":           "./src/index.ts",
  "./styles.css": "./src/styles.css"
}

消费方需同时导入 @blksails/pi-web-ui/styles.css（Tailwind 样式入口）。

支持 Storybook 开发：pnpm --filter @blksails/pi-web-ui storybook（端口 6006）。

@blksails/pi-web-agent-kit

职责：给自定义 agent 作者使用的轻量型帮助包。defineAgent() 是纯 identity 函数，仅提供编译期类型检查，零运行时副作用——即使不使用本包，定义的 AgentDefinition 结构与 runner 的要求完全兼容。

依赖：@blksails/pi-web-protocol；peer dep: @earendil-works/pi-coding-agent（仅类型）。

主要导出：

// 定义入口
export function defineAgent(def: AgentDefinition): AgentDefinition
 
// 类型
export type { AgentDefinition, AgentContext, AgentModel }
export type { ToolDefinition, SystemPromptValue, ThinkingLevel, ... }
 
// 便利
export { defineMinimalAgent, minimalAgentPreset }
export { emitUi }                    // 工具内发出 data-pi-ui 部件
 
// 附件 tool 上下文（仅类型，运行期构造在 @blksails/pi-web-server）
export type { AttachmentToolContext, AttachmentToolHandle, ... }

用法示例：

// <agent-dir>/index.ts
import { defineAgent } from "@blksails/pi-web-agent-kit";
 
export default defineAgent({
  // 省略 model → 继承 ~/.pi/agent/settings.json 的默认 provider/model，开箱即用。
  // 如需固定模型：model: { provider: "anthropic", modelId: "claude-opus-4-5" }
  //（但对应 provider 必须有有效凭据，否则 LLM 调用会失败）。
  systemPrompt: "You are a helpful assistant.",
});

可直接参考仓库 examples/hello-agent/index.ts:1（带自定义 echo 工具的最小可运行 agent）。详细用法见 07 · Agent 开发。

@blksails/pi-web-tool-kit

职责：通用工具套件。分为两层——主入口（前端安全声明层）和 ./runtime 子入口（Node only 执行层）。

依赖：@blksails/pi-web-agent-kit、undici（运行层）；peer deps: @earendil-works/pi-ai、@earendil-works/pi-coding-agent。

exports 字段：

{
  ".":         "./src/index.ts",    // 声明层，前端安全
  "./runtime": "./src/runtime.ts"   // 执行层，Node only
}

主入口（声明层）：

export * from "./engine/types.js"         // 引擎类型
export { AIGC_TOOLS, imageGeneration, imageEdit }  // AIGC 工具声明

./runtime 子入口（执行层）：

凡含 pi SDK 值导入的逻辑一律放 ./runtime，严禁混入主入口，以守 Next/webpack externals 边界。

@blksails/pi-web-kit

职责：agent source .pi/web 的作者侧 SDK（UI 控制层），与 @blksails/pi-web-agent-kit 对称——defineAgent() 对应 defineWebExtension()。作者写 .pi/web 入口，默认导出 WebExtension；随包发布的 pi-web build CLI 预构建为 ESM bundle + manifest。

依赖：@blksails/pi-web-protocol、esbuild（构建工具）；peer deps: react、ai。

exports 字段：

{
  ".":       "./src/index.ts",
  "./build": "./build/index.ts"    // 构建 CLI 入口
}

bin 入口：pi-web → ./build/cli.ts

主要导出（稳定核）：

export { defineWebExtension }         // identity helper + 类型
export type { WebExtension, SlotContribution, ContributionPoints, ... }
export { SLOTS }                      // 插槽常量表
export type { UiRpcClient }           // 宿主↔扩展 RPC 类型
export type { WebExtHostContext }
// protocol re-export（可序列化契约）
export type { SlotKey, WebExtConfig, ArtifactDeclaration, UiRpcPoint, ... }

用法示例：

// <agent-dir>/.pi/web/web.config.tsx
import { defineWebExtension } from "@blksails/pi-web-kit";
 
export default defineWebExtension({
  manifestId: "my-ext",            // 必填:扩展唯一标识
  capabilities: ["slots"],
  slots: {
    // SlotKey 为 camelCase(panelRight / headerLeft / artifactSurface …);
    // 贡献值可为 ReactNode,或受 { extId } props 的组件。
    panelRight: <MyPanel />,
  },
});

插槽 key 取自 SLOTS 常量表（SLOTS.panelRight 等），亦可直接写字面量；可用插槽全集见 packages/web-kit/src/slots.ts:8 与 10 · Web UI 扩展。完整可运行范例见仓库 examples/webext-slots-agent/.pi/web/web.config.tsx:1。

规划中的包

依赖方向速查

@blksails/pi-web-protocol  ←──────── 所有包
@blksails/pi-web-server    ────依赖──→ @blksails/pi-web-protocol 只
@blksails/pi-web-agent-kit ────依赖──→ @blksails/pi-web-protocol 只
@blksails/pi-web-tool-kit  ────依赖──→ @blksails/pi-web-agent-kit
@blksails/pi-web-kit   ────依赖──→ @blksails/pi-web-protocol
@blksails/pi-web-react     ────依赖──→ @blksails/pi-web-protocol + @blksails/pi-web-kit
@blksails/pi-web-ui        ────依赖──→ @blksails/pi-web-protocol + @blksails/pi-web-react + @blksails/pi-web-kit

禁止：server ↔ react/ui（后端与前端不互相依赖）
禁止：protocol 反向依赖任何包

下一步 / 相关文档

• 03 · 架构总览 — 各包在运行时的拓扑与进程边界
• 05 · 配置参考 — @blksails/pi-web-server/model-options 与环境变量
• 07 · Agent 开发 — @blksails/pi-web-agent-kit 与 defineAgent() 的详细用法
• 09 · 扩展与技能 — @blksails/pi-web-kit 与 defineWebExtension()
• 11 · AIGC 工具 — @blksails/pi-web-tool-kit/runtime 的 buildAigcTools
• 13 · HTTP API 参考 — @blksails/pi-web-server HTTP 模块的路由约定