@gencode/shared

包定位

@gencode/shared 负责跨包共享的稳定类型与协议定义。 它存在的目的，是防止 agents、cli、web 等包之间出现协议漂移和镜像定义。

负责内容

这个包适合承载：

• 稳定共享类型
• 被多个包复用的 request / response 协议结构
• callback payload 结构
• websocket 事件载荷结构
• 共享的 run-event / progress-event 定义
• HITL、UI-tool 等跨包共享契约

不负责内容

这个包不应包含：

• 包特定的运行时编排逻辑
• transport 副作用
• Web 服务行为
• CLI 命令逻辑
• agent 领域逻辑

当前源码入口

阅读本包时，建议先看：

• src/index.ts —— 对外导出入口
• src/agent-progress.ts
• src/context-protocol.ts
• src/hitl.ts
• src/run-events.ts
• src/ui-tool.ts

当前测试包括：

• src/agent-progress.test.ts
• src/context-protocol.test.ts
• src/hitl.test.ts
• src/run-events.test.ts
• src/ui-tool.test.ts

当 dist/ 存在时，应将其视为构建输出，而不是源码事实来源。

与其他包的关系

• 当 @gencode/agents 的内部结果需要对外形成稳定共享结构时，应优先使用本包
• @gencode/cli 应尽量消费本包中的共享协议，而不是本地重新定义
• @gencode/web 在消费 CLI 输出时，也应尽量与本包中的契约保持一致

开发说明

一个类型或协议通常应该放在这里，当它满足以下条件之一：

• 被多个包共同依赖
• 描述了稳定的跨包契约
• 若出现镜像定义，漂移风险较高

一个类型通常不应放在这里，当它：

• 只在单个包内使用
• 仅服务于某个内部实现细节
• 附带运行时行为，而不是共享结构

验证

在工作区根目录可运行：

pnpm -C source/packages/shared test

工作区级验证：

pnpm -C source typecheck
pnpm -C source test

相关规格文档

• ../../../specs/system-overview.md
• ../../../specs/architecture-boundaries.md
• ../../../specs/repo-map.md
• ../../../specs/implementation-backlog.md