# @gencode/agents

## 包定位

`@gencode/agents` 是 agent 核心领域层。
它应成为 agent 执行流程、session 相关领域能力以及内部运行期事件的主要归属位置。

## 负责内容

这个包适合承载：
- agent 执行流程
- session 领域行为
- memory / bootstrap / identity 相关领域能力
- 内部运行期协调
- 结构化内部事件产出
- 不依赖外部传输层的 agent 核心抽象

## 不负责内容

这个包不应直接承担以下进程外通信职责：
- stdout 渲染
- HTTP callback 投递
- websocket 传输投递
- Web 服务侧逻辑
- CLI 参数解析

这些职责属于 `@gencode/cli` 或更高层的集成包。

## 当前源码入口

阅读本包时，建议先看：
- `src/index.ts` —— 主入口
- `src/types.ts` —— 包内类型定义
- `src/session/artifact-store.ts` —— Session 累计最终产物 V2 存储
- `src/tools/record-artifacts.ts` —— root-only 显式产物登记工具与本轮 artifacts / operations 集合
- `src/runner/finalizer.ts` —— 将非空本轮 artifacts 与有界 operation 摘要投影到 run result 和最后一条 assistant transcript entry
- `src/build-config.test.ts` —— 当前包级验证示例

当 `dist/` 存在时，应将其视为构建产物，而不是主要编辑目标。
优先阅读源码与测试。

## 与其他包的关系

- `@gencode/cli` 使用本包执行 agent 行为，并把内部事件适配为外部输出
- `@gencode/shared` 应承载稳定的跨包协议，而不是在本包内重复定义
- `@gencode/web` 不允许绕过 CLI 直接消费本包

## 开发说明

当你在这里增加新能力时：
- 保持职责在领域侧，而不是传输侧
- 优先返回显式接口与结构化输出
- 不要把 callback / websocket 认知嵌入 agent 内核
- 当一个对外结构开始被多个包复用时，应优先沉淀到 `@gencode/shared`

## 验证

在工作区根目录可运行：

```bash
pnpm -C source/packages/agents test
```

类型检查通常通过工作区命令统一运行：

```bash
pnpm -C source typecheck
```

## 相关规格文档

- `../../../specs/system-overview.md`
- `../../../specs/architecture-boundaries.md`
- `../../../specs/development-workflow.md`
- `../../../specs/repo-map.md`
- `../../../specs/final-artifacts.md`