Imported from wojzj57/ps-generator-bridge-service (
AGENTS.md). Install upstream withnpx skills add wojzj57/ps-generator-bridge-service. Copyright stays with the author.
PS Generator Bridge Service - AI Agent 导航图
渐进式披露入口。先读此图，再按任务类型跳转到对应深度文档。
项目一句话
PS Generator Bridge Service 是一个 Photoshop Generator monorepo：generator 插件运行在 Photoshop
内置 Node runtime 中并拥有 WebSocket server；sdk 是同构客户端，也是协议契约的真相源。
按任务快速导航
| 你的任务 | 先去这里 | 说明 |
|---|---|---|
| 了解整体术语与边界 | CONTEXT.md |
Ubiquitous language，先统一 server / plugin / module / protocol 等词 |
| 改协议或新增能力 | packages/sdk/src/protocol/ |
ProtocolMethods 是服务能力的 source of truth |
| 改 Photoshop Generator host | packages/generator/ + packages/generator/TESTING.md |
@ps-generator-bridge/generator；In-PS Generator 插件、Fastify/WebSocket server、模块、插件加载与测试边界 |
| 改 SDK client | packages/sdk/ |
@ps-generator-bridge/sdk；同构客户端，保持 browser-safe / Node-free，不要把 server 类型泄漏进 SDK root |
| 改 CLI / smoke harness | packages/cli/ |
@ps-generator-bridge/cli；Windows Photoshop + generator-core smoke harness |
| 写公开文档 | docs/ + package README |
GitHub 与 GitHub Pages 的公共文档来源 |
| 查包导出边界 | docs/reference/package-exports.md |
SDK root、SDK plugin subpath、generator CJS 入口的公开面 |
30 秒项目速览
- 包管理器：
pnpmworkspace。 - 核心命令：
pnpm build、pnpm typecheck、pnpm test。 - 真实 PS 运行准备：
pnpm setup会在用户级统一缓存中准备 Adobegenerator-core和最新 generator runtime。 - 协议真相源：新增服务能力先改
packages/sdk/src/protocol/，再实现 generator server。 - SDK root 约束：
@ps-generator-bridge/sdk必须保持 browser-safe，不引入 Node/server/Fastify/COS SDK 类型或 runtime。 - 插件开发面：外部子插件使用
@ps-generator-bridge/sdk/plugin。 - 测试策略：TypeScript unit tests 通过 seam 注入（
FakeGenerator、FakeTransport），不需要真实 Photoshop。
包结构地图
├── packages/
│ ├── sdk/ @ps-generator-bridge/sdk，同构客户端 + 协议契约
│ ├── generator/ @ps-generator-bridge/generator，Photoshop Generator 插件 + WS 服务
│ └── cli/ @ps-generator-bridge/cli，Windows PS + generator-core smoke harness
├── docs/ 公开 VitePress 文档
├── CONTEXT.md 术语表 / ubiquitous language
└── notes/ 本地私有开发笔记（gitignored，默认不要读取）
关键约定速查（不可违背）
- Protocol 是 source of truth：新增 server capability 必须先建模到
packages/sdk/src/protocol/的ProtocolMethods，再实现 server。 - SDK root 保持 Node-free / browser-safe：不要把 Fastify、
ws、COS SDK、generator-core、server concrete types 泄漏到packages/sdkroot。 @ps-generator-bridge/sdk/plugin是插件作者入口：BasePlugin、decorators、plugin authoring runtime、plugin-only helpers 都从这里导出。- 跨 bundle handshake 不能乱改：
Symbol.for("ps-generator-bridge.*")keys 是外部插件互操作契约，改名会破坏跨 bundle 行为。 - generator 只 type-only 依赖 SDK 协议契约：运行时代码可以经 tsup alias 内联 SDK source，但不要制造发布后 runtime 循环依赖。
- Config vs env 分层：secrets 和部署旋钮走
PS_BRIDGE_*env vars；结构化运行参数（如port、pluginsDir）走PluginConfig，env 只做 override。 - 测试不依赖真实 Photoshop：unit tests 使用
FakeGenerator、FakeTransport和注入 seam；真实 Photoshop 只属于 smoke harness 范围。 - 不要默认读取
notes/：notes/是本地私有知识库，除非用户明确要求，否则 agent 不得读取或依赖。
Log规范
Logger 统一从 @ps-generator-bridge/sdk/plugin 导入 useLogger，在模块顶层以短小稳定的领域名（如 selection、image、plugin-loader）创建 const log = useLogger("<name>")，并仅使用 log，不要混用 logger、console.* 或 this.plugin.logger。
文档边界
-
开发代码、新增功能或修复 Bug 时不需要同步更新文档，文档更新由独立流程处理。
-
docs/是 GitHub 和 GitHub Pages 的公共文档来源。 -
notes/是本地私有开发知识库，gitignored；默认不要读，也不要作为公共文档依据。 -
公共文档必须基于 repository source、tests、package README、公开 docs 和用户提供的需求，而不是私有 notes。
常用命令
pnpm install
pnpm setup
pnpm build
pnpm typecheck
pnpm test
pnpm docs:dev
pnpm docs:build
pnpm docs:preview深度文档
docs/README.md- 公共文档入口。CONTEXT.md- 术语表 / ubiquitous language。packages/generator/TESTING.md- generator unit test 范围与边界。docs/reference/package-exports.md- package exports 与 public API 边界。
