# Changelog

此项目的所有显著变更都将记录在此文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/2.0.0/)，
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

> 此 changelog 从项目初始化（2026-07-24）开始记录。首次正式发布 0.1.0（2026-08-03），此前全部变更汇集于此版本；后续变更记入 `[未发布]`。

## [未发布]

## [0.3.0] - 2026-08-08

### 新增

- 消息来源显式化：公开消息协议新增 `source` 字段（首版唯一取值 `group`，缺省即群聊，向后兼容）；群聊输入注入显式声明「来源：群聊」（与身份行同批）；私聊无协议标记、不进入公共消息流，角色侧处理规则（不广播、需群知时显式发布并注明来源）已落入角色卡。
- ready 欢迎消息：角色进入群聊后单播一条 `system_message` 欢迎语，支持项目配置、全局配置与内置默认值三档优先级。

### 变更

- **不兼容变更**：协议层迁移 JSON-RPC 2.0 标准信封，判别字段 `type` → `method`、载荷进 `params`、响应改 `{result}`/`{error}`；请求/响应必带 id（无 id 拒绝）；错误码纳入 JSON-RPC 标准码。0.2.x 客户端无法与 0.3.0 混用（一次性豁免零漂移）。
- 进入群聊后不再自动推送历史：角色按需通过 `tavern_history` 连续向前分页回看，增量消息继续按 Session 独立游标追赶；欢迎语不进入公共消息流。
- 群聊拉取增加窄上下文窗口：向 Agent 投递全部未读消息时，附加一条紧邻的已读消息作为上下文；没有未读消息时不重复注入。
- 协议定义 docs-first：JSONC 成为协议定义唯一手写源，TypeBox schema 由翻译器生成，并由只读漂移门禁校验。

### 文档

- 新增「海龟汤」群聊文字局规则，并按 PiTavern 的公开消息流、讨论轮次与角色自主发言机制补充实战约束。

## [0.2.1] - 2026-08-06

### 文档

- README 开头补充中英双语产品简介，并强化首次使用指引：安装后先创建角色卡、通过 `tavern.json` 导入，再创建并加入群聊。

## [0.2.0] - 2026-08-05

### 新增

- 白板模型：头脑风暴状态收敛机制——每角色一块自己的白板（贴条/撕条/清板/查询），全群可见，更新发增量摘要通知（「喊一声」），默认 5 条 / 140 码点（可配置），随群聊删除同步清理。
  - 协议：`board_write`（贴/改/撕/清，四态响应 + 五码 reason_code：拒绝 2 码 + 告知 3 码）、`board_query`（全量）、`board_update`（增量通知：谁/动作/内容，写者本人回显自动过滤）。
  - 行为：每人只能写自己的板；超限/超长明确报错；无变化操作接口层告知、群聊静默（有变化才通知）；贴条不占发言额度；通知走既有环境事件批处理窗口合并（1s）。
  - 入口：角色侧 `tavern_board` 工具 + 白板更新桶渲染；creator 侧 `/tavern-status` 白板小节 + 实时提示（纯展示）。
  - 里程碑 B0-B6 完成：协议 codec / board-store（原子写、损坏降级、deleteBoard 清理）/ 消息通路 / 角色侧接线 / User 入口 / 三层测试（unit 253 + integration 128 + acceptance 3，全绿）。
- 环境文本加时间：群聊输入消息带发言时间、距当前间隔与头部当前时间，帮助 Agent 感知时间流逝。
- `tavern_speak` 未读先读：发言前发现他人未读时先告知不发布，settle 拉全后以完整上下文重新决策；不耗发言额度、不举手。

### 变更

- 忙态通知改为 steer 安全边界打断：当前工具批完成后才 abort，settle 拉全未读并通过 follow-up 重开。
- A/B 类错误消息与用户文案集中到 `src/shared/messages.ts`，减少跨模块文案漂移。
- 发布为可发现的 Pi package：npm 包名 `pi-tavern`，保留 Git 安装方式，并以 `pi-package` 关键词进入 pi.dev package gallery。

### 修复

- 修复 `tavern_board` 顶层工具参数 schema，恢复 Pi 工具注册兼容性。
- 断连后停止流式状态上报竞态：连接未建立或已关闭时展示态上报静默跳过，并清理相关 watchdog。

### 文档

- 新增「谁是卧底」群聊文字局规则与双语使用案例。
- 历史文档语言审计与全仓注释中文化，保持标识符和契约语义不变。
- README 增加小规模团队与外部顾问工作流说明。

### 安全

- 凭据泄漏修复：测试环境改用白名单变量，保持零 LLM、零外部网络，并补充凭据文件忽略规则。

## [0.1.0] - 2026-08-03

### 新增

- PiTavern 扩展运行时：本地群聊扩展的 pi-coding-agent 宿主集成骨架。
- creator 进程生命周期：群聊创建、持久化、round 讨论轮次与发言配额。
- character 进程加入生命周期：角色以独立 pi session 身份加入群聊、群聊状态同步。
- 公开对话循环：角色间通过群聊公开发言协作、round 轮转。
- 历史恢复：会话文件追加写入 + 游标只前进 + 写中断恢复（FIRST_PERSIST 机制）。
- pi 生命周期对齐：扩展随 pi 启动/退出，reload 交接与崩溃收敛。
- 进程级验收：多进程端到端验收套件。
- 角色卡系统：角色卡驱动角色身份与协作守则，reload 热刷新角色清单；架构师角色卡加入，四方（PM/Dev/QA/Arch）协作化。
- 群聊历史分页拉取：join 后全量历史可查。
- 新消息获取推拉混合：join 拉取 + 活跃期推送。
- resume 历史投影：崩溃/重启后按游标扫描锚定恢复对话历史，不重不漏。
- TUI 增强组：渲染精度、终端尺寸自适应等。
- 发言落后校验契约与 TUI CPU 结论固化。
- 游标按 Session 隔离：同群聊多角色各持独立游标文件（`cursors/<groupId>/<sessionId>.json`），互不踩踏。
- run wedged watchdog：角色 run 卡死超时（默认 180s，可注入）自动强制收敛——排队消息不再无限滞留，迟到真实 settle 不会双重冲刷。
- 五层架构重构 Phase 2+3 完成：application 层六管线门面化 + runtime 瘦身（creator-runtime 1881→429 行骨架，拆出十模块）+ index.ts 唯一装配点。
- AGENTS.md：面向 AI agent 的项目指令（核心原则 + 必须加载的上下文索引）。
- 角色卡清单按需刷新：join/claim/query 前懒重扫角色清单，扫描失败回退旧快照——新角色与 name/description 变更无需重建群聊。

### 变更

- 消息同步改为 pull 模型：广播降级为纯标记（latest_sequence 水位），消费点在 run 组装时一次拉全未读、整批聚合发 LLM，活跃 run 零中间注入。
- run 中消息投递：steer 间隙投递改为秒级延迟、不打断进行中的 run。
- 活跃期增量聚合窗口：多次打断 N 条消息 → 单次投递（N→1），固定 400ms 窗口 + settle 尾部兜底。
- 群聊消息数量上限 10 → 100。
- 五层架构重构 Phase 1：resume-projection / discovery / session·cursor store 归位 `src/data/`（skills 层），行为零变化、契约零 diff。
- 旧共享游标废弃：新 Session 无独立游标时从完整历史拉取（重复可接受、跳过不可接受），不再采用无 Session 身份的旧群聊级游标（修复升级后可能跳消息的窗口）。
- README 全面重写：定位「面向独立 Agent Session 的生命周期感知异步群聊」；团队组合示例六案例（三软件 + 三非软件、职位化、双层免责）；安装（开发版）+ 快速开始；中文主版 + 英文对等版。
- 测试机制：默认不跑用例——验证必须显式指定目标（`npm run test:unit -- <pattern>` / `-- --all` 层内全量 / `test:full` 三层串行收口），无参调用拒绝（exit 1）并打印指引。
- 验收套件提速：四场景 family 化聚合（13→10 文件）+ streaming-truth 并发化（100.9s→26.9s）+ 孤儿 pi 进程自动清理；全量 83.6s。
- 协作流程：并发协作（前置产物先行/红钉先行/阶段重叠/预跑窗口）、Arch 承担 code review（评审从严、代码洁癖）、落盘文件清单核对（workflow v1.0–v1.3）。
- 测试耗时 152s → 87s → 83.6s：假 key 注入 + tsx 预热 + worker 定档 + acceptance family 重构/并发化/孤儿清理。
- 忙态消息投递恢复工具间隙可见（User 拍板）：run 活跃期间新消息经 steer 通道在工具调用间隙到达（秒级可见），不再等 run 结束才批量进入；绝不打断进行中的 run；游标在投递入队成功时推进，失败由 settle 兜底重投（不丢不重）。
- 闲态触发窗口可注入：`PITAVERN_TRIGGER_DEBOUNCE_MS`（默认 1000ms 行为不变），需要更快感知的环境可设短值（idle 感知延迟降 ~750ms）。
- 依赖方向由 lint 强制：`npm run lint:layers`（adapter 禁 skills 行为面 / application 与 runtime 禁直连 node:fs，组合根与工厂豁免），与 biome 同入 CI 门禁。
- TUI 状态语义「正在发言」→「正在工作」：run 活跃即亮（agent_start 无条件点亮），标记机制删除、复位三件套保留（agent_end / 5s watchdog / wedged 3min）——长 run 常亮为预期行为。
- 仓库健康度检查：`npm run health` 三合一体检——npm audit 依赖漏洞 / gitleaks 凭据扫描 / 卫生自查（未提交改动、残留分支、超大文件）；纯本地手动命令，不做 CI 集成。
- J 系列投递边界钉测：长 run 循环输入不丢投递（unit）/ RPC 中途 abort 不清队（acceptance，0→1→abort→1→2 完整序列）/ 半开恢复断连不丢（integration）；双版本（pi 0.82.1-1 vs 0.83.0）行为一致三路实证（RPC 实测 + 源码 diff + 176 commits 检索）。

### 变更

- 本地门禁清理：存量 biome/TS 欠账清零 + husky pre-push 钩子（推送自动跑全量 check，非零拒绝）——合入 main 前 check 全绿留痕为合入三件套之一。
- 协作流程 v1.4：§7.6 机制九条（状态以 git log 为准 / 分工矩阵 / 等待窗口显式化 / 钉测即验收 / PM 总收尾 / 验收两级制试点 / 测试分层下沉 / 双 worktree 声明制）+ PM 落盘职责边界（机械修复先声明、语义修改归属主）。
- 验收基线刷新：0.1.0 基线三层全量 338 用例 ≈102.9s（acceptance 11 文件含 J 系列/W1-c 新钉测负载，非性能回归）；旧 34/45 基线废弃标注留档。

### 修复

- typebox 依赖移至 dependencies，git 安装可正常加载。
- 群聊历史分页拉取修复：join 后历史全量可查。
- 消息同步修复 + headless 模式 CPU 占用根治。
- 验收套件 CPU 峰值 8 核 → 1.5 核（限 2 worker）；负载敏感超时用例定档。
- 重构值拷贝注入陷阱修复：deps 中可重赋值字段/回调改 getter 闭包活引用（onPublicMessage/runtimeTail/lifecycle 族），消除 close/drain 竞态（Phase 3 PR-B）。
- 验收游标断言修复：headless/live-delivery 改读 Session 隔离路径（共享 cursor-helper，断耦实现路径）。
- 验收卡死修复：孤儿 pi 进程自动清理（10 个孤儿曾致全量 >600s 未完成）。
- 忙态游标推进竞态修复（T2）：投递确认短承诺化（入队接受即推进游标），消除并发拉取下同一窗口重复投递。