sync: taiji 稳定版同步最新基线 aa982617a（群聊交付 + CI 治理 + 上游合流）

AGENTS-CN.md

@@ -176,6 +176,25 @@ BitFun 不是只在本地运行的桌面应用：工作区、执行这一轮的
 
 改动说明中要写清楚在哪些远程场景下验证过。只跑本地测试不能作为远程行为的证据。
 
+### 升级兼容性
+
+用户是原地升级的，而上述远程场景经常让两个不同版本的 BitFun 连在同一条链路上。
+任何改动都必须保证已有安装在升级后无需手工修复即可继续工作。
+
+- **落盘结构会被新旧两侧代码同时读取。** 配置、设置、会话、连接配置、worktree 和
+  dispatch 记录：新增字段要带默认值，反序列化要保持容错，绝不重新定义或收窄已经落盘
+  字段的语义。旧数据给不出的字段，不能变成必填。
+- **不要用删除或重置用户数据的方式来“恢复”解析不了的内容。** 应保留记录、降级功能并
+  给出明确状态。凭证缺失、配置读不出、超时或主机离线，都不构成丢弃会话、工作区或连接
+  的理由；销毁性删除只能是用户的显式操作。
+- **跨版本边界要协商，不能假设。** Peer HostInvoke、dispatch 协议、relay 与 mobile web、
+  IM Bot，对面都是你控制不了的构建版本。要先声明 capability 再使用——包版本相同不等于
+  行为相同——并且要让旧版本一侧留在可用路径上，而不是直接判失败。
+- **改名就是一次迁移。** 在所有受支持的对端都不可能再发送旧名称、旧 id 或旧结构之前，
+  必须继续兼容读取；被改名对象所引用的数据（vault 条目、工作区指针）要一并迁移。
+- **用测试证明。** 要覆盖旧数据反序列化和旧载荷往返，而不只是新结构。只验证当前代码
+  自己写出的数据，不算升级兼容性覆盖。
+
 ### Agent loop 行为
 
 - 不要把硬编码限制或模式判断作为处理 agent loop 循环问题的第一反应，例如仅按字符串或次数阻止重复工具调用。

AGENTS.md

@@ -206,6 +206,34 @@ Per-scenario obligations:
 State which remote scenarios a change was exercised in. Local-only tests are not
 evidence of remote behavior.
 
+### Upgrade compatibility
+
+Users upgrade in place, and the remote scenarios above routinely put two
+different BitFun versions on the same connection. Every change must keep
+existing installs working without manual repair.
+
+- **Persisted shapes are read by older and newer code.** Config, settings,
+  sessions, connection profiles, worktree and dispatch records: add fields with
+  defaults, keep deserialization tolerant, and never repurpose or narrow the
+  meaning of a field that is already on disk. A field old data cannot supply
+  must not become required.
+- **Never delete or reset user data to recover from something you cannot
+  parse.** Keep the record, degrade the feature, and surface a clear state.
+  Missing credentials, an unreadable profile, a timeout, or an offline host are
+  not reasons to drop a session, workspace, or connection. Destructive removal
+  stays an explicit user action.
+- **Cross-version boundaries negotiate; they do not assume.** Peer HostInvoke,
+  the dispatch protocol, relay and mobile web, and IM bots all talk to a build
+  you do not control. Advertise a capability and check it before using it —
+  package version equality is not evidence of behavior — and keep the older
+  side on a working path instead of failing it.
+- **A rename is a migration.** Keep reading the old name, id, or record shape
+  until no supported peer can still send it, and migrate referenced data
+  (vault entries, workspace pointers) together with the thing being renamed.
+- **Prove it with tests.** Cover legacy deserialization and an old-payload
+  round trip, not just the new shape. A test that only exercises data written
+  by the current code is not upgrade coverage.
+
 ### Agent loop behavior
 
 - Do not add hard-coded limits or pattern checks to the agent loop as a first response to looping behavior, such as blocking repeated tool calls by string or count alone.