work-ally 0.2.0-alpha.1

package/docs/planning/SPEC-minimal-bridge-semantics-and-user-visible-surface.md

@@ -0,0 +1,362 @@
+# SPEC: 极简桥梁语义与前台可见面收口
+
+更新时间：2026-03-18  
+状态：Shipped / 2026-03-18 baseline  
+Owner：work-ally product / engineering  
+相关文档：
+- `docs/planning/SPEC-bridge-app-server-protocol-alignment.md`
+- `docs/planning/SPEC-session-presence-and-state-visibility.md`
+- `docs/issues/pending/ANALYSIS-ally-premature-recovery-notice-and-task-state-semantics-2026-03-18.md`
+- `PRODUCT.md`
+- `AGENTS.md`
+
+## 1. Summary
+
+这份 spec 要把 `work-ally` 的 bridge 前台语义进一步收回到一个更克制、更稳定的边界：
+
+> `work-ally` 默认不是“任务解释器”，而是 **Feishu <-> Codex App Server 的稳定桥梁 + 最小必要辅助层**。
+
+这次收口不解决“桥能不能恢复”这个底层能力问题，而是解决另一个更根的问题：
+
+1. 哪些信息真的应该让用户看到
+2. 哪些只是 bridge 内部的收敛过程，不该变成前台提示
+3. 哪些提示属于必要协作信号，哪些提示只是中间层在解释自己
+
+本次完成后，bridge 用户面默认只保留：
+
+- reaction ack
+- 真实 runtime 中间输出
+- 审批 / 补充输入 / 明确等待用户动作
+- 最终结果
+- 明确不可自动补偿时的兜底失败提示
+- 上一轮结果未稳定送达时的补发提示
+- 显式 slash 控制命令的结果
+
+除此之外，bridge 不再默认暴露自己的内部任务语义、内部 recovery 过程和内部状态清理过程。
+
+## 2. 背景
+
+最近几轮稳定性治理已经证明两件事：
+
+1. 内部 ledger、pull-primary、recovery、redelivery 这些骨架是必要的
+2. 但如果把这些内部状态继续翻译成大量用户提示，中间层就会重新变厚
+
+用户当前对产品边界的要求已经很明确：
+
+- `work-ally` 最本质的工作，是在 Feishu 和 Codex App Server 之间稳定转交消息与结果
+- bridge 只做必要的辅助工作，不做第二套“任务脑”
+- 只有在用户必须行动，或系统必须诚实告知无法继续时，才应该前台出声
+
+此前的 recovery notice 问题已经暴露出一个典型风险：
+
+- bridge 明明只是内部在补确认
+- 但前台却先收到了“任务状态暂未确认”这类中间层自创解释
+- 这会让用户误以为 bridge 掌握了一套高于协议事实的权威状态
+
+所以，这次不是单纯修一句文案，而是继续把 bridge 前台语义收薄。
+
+## 3. 问题定义
+
+当前系统还存在 4 类偏厚点。
+
+### 3.1 bridge 仍在前台解释自己的内部 recovery 过程
+
+例如：
+
+- `系统正在继续确认这一轮结果。`
+- 其他 recovery / unconfirmed 解释型提示
+
+这些文案虽然比“任务状态”更克制，但本质上仍然是 bridge 在解释自己的内部收敛过程。
+
+### 3.2 bridge 仍在前台解释自己的内部状态清理动作
+
+例如：
+
+- `检测到上一轮残留的未完成状态；已清理旧状态，改为处理你刚发的新消息。`
+
+这类文案描述的是实现层行为，不是用户真正需要掌握的协作事实。
+
+### 3.3 文档口径仍把“任务语义状态”当作稳定产品面
+
+当前 README / quickstart / manual acceptance / presence spec 仍带有：
+
+- 任务语义状态
+- 恢复中提示
+- 用户应该看到哪些中间状态
+
+这会把 bridge 往“轻量工作流状态机”方向继续推厚。
+
+### 3.4 “什么该前台可见”没有一条更硬的统一原则
+
+虽然已有 KISS 原则，但在 bridge 用户面这一层，还缺一条足够明确的执行规则，导致后续遇到故障或新 feature 时，很容易再往前台塞解释性提示。
+
+## 4. 目标
+
+本次收口必须达成下面 6 个目标：
+
+1. 明确 bridge 前台默认只转发协议事实、协作事实和必要动作提示
+2. 去掉默认用户语汇里的“任务状态”与等价厚语义心智
+3. 默认不再把短暂 recovery、内部 reconciliation、内部状态清理过程暴露给用户
+4. 保留审批、补充输入、重发兜底、补发兜底、slash 控制结果这些必要用户信号
+5. 让 README / quickstart / manual acceptance / planning spec 一起回到同一条边界
+6. 给后续工程一个清晰规则：除非满足“必须让用户现在行动或现在知道”，否则不要新增系统提示
+
+## 5. 非目标
+
+本次明确不做：
+
+1. 不删除内部 ledger / recovery / redelivery / pull-primary 机制
+2. 不改变审批、自测默认授权、handoff、same-machine session 等现有产品合同
+3. 不重做 UI 卡片协议
+4. 不在本期讨论桌面端诊断面要展示哪些内部状态
+5. 不否认“少量事实型提示”在某些场景下的必要性，但要把默认边界收紧
+
+## 6. 核心产品原则
+
+本次之后，bridge 前台统一遵守下面这条总原则：
+
+> 默认只转发事实，不解释内部状态；只有用户必须行动，或系统必须诚实告知无法继续时，才显式打断。
+
+这里的“事实”，只允许来自三类来源：
+
+1. 官方协议事实
+   - approval request
+   - user input request
+   - turn 最终结果
+2. 桥接交付事实
+   - 上一轮结果当时未稳定送达
+   - 现在正在补发 / 补发失败
+3. 显式用户控制结果
+   - `/stop`
+   - `/new`
+   - `/takeover`
+   - `/codex`
+   - `/approve` / `/deny`
+
+凡是不属于这三类的，默认都应先视为 bridge 内部实现细节，而不是用户提示候选。
+
+## 7. 用户可见面的最小集合
+
+V1 收口后，用户前台只保留下面 6 类可见信号。
+
+### 7.1 已收到
+
+- 保留 reaction ack
+- 不额外补“已收到，开始处理”文本状态
+
+### 7.2 Codex 真实进度
+
+- 有真实 runtime commentary / progress 时，转发
+- 没有真实进度时，不为了“显得系统没死”而编造一般性说明
+- heartbeat 只作为极少数必要兜底，不作为主状态面
+
+### 7.3 等待用户动作
+
+必须保留：
+
+- approval card
+- user input prompt
+- 对应的“现在轮到你了”最小说明
+
+因为这类信息直接决定用户是否需要立即行动。
+
+### 7.4 显式控制结果
+
+必须保留：
+
+- `/stop` 的明确结果
+- `/new` 的明确结果
+- `/takeover` / `/codex` / `handoff attach` 相关结果
+- `/approve` / `/deny` 的结果
+
+因为这类信息直接对应用户明确下达的控制动作。
+
+### 7.5 最终结果与明确失败
+
+必须保留：
+
+- final reply
+- completion without reply 的最小结束提示
+- 在完整补偿后仍无法确认这一轮是否完成时，明确要求用户重发上一条消息
+
+### 7.6 上一轮未稳定送达
+
+必须保留：
+
+- 上一轮结果未稳定送达时的补发提示
+- 补发失败时的最小说明
+
+因为这是 bridge 作为稳定桥梁必须诚实告诉用户的交付事实。
+
+## 8. 默认不再前台暴露的内容
+
+下面这些内容，在默认用户路径里应收回内部：
+
+### 8.1 内部 recovery 尝试过程
+
+默认不再提示：
+
+- bridge 正在补确认
+- bridge 正在做 final-state reconciliation
+- bridge 正在做内部 recovery attempt
+
+除非超过明确阈值后仍未收敛，并且已经进入必须对用户诚实告知的阶段。
+
+### 8.2 内部状态清理动作
+
+默认不再提示：
+
+- 发现残留状态
+- 已清理旧状态
+- 已改为处理新消息
+
+正确做法应是：
+
+- bridge 内部完成清理
+- 然后直接进入新一轮正常处理
+- 除非这个清理动作改变了用户必须知道的产品语义，否则不出声
+
+### 8.3 transport / reconciliation / ledger 术语
+
+默认不在用户前台出现：
+
+- reconnecting / disconnected / recovered 这类实现层术语
+- reconciliation / ledger / pending_recovery / delivery_unavailable 这类内部术语
+- “任务状态”这类 bridge 自创总括语义
+
+## 9. 机制设计
+
+### 9.1 内外分层
+
+要明确分成三层：
+
+1. 内部稳定性层
+   - turn ledger
+   - recovery
+   - redelivery
+   - pull-primary
+   - pending_recovery / recovery_required / delivery_unavailable
+2. 协议 / 交付事实层
+   - approval / user input / turn result / delivery outcome
+3. 用户前台层
+   - 只取第 2 层中用户现在必须知道的部分
+
+这三层必须继续分离，不能再用前台文案直接暴露第 1 层内部状态。
+
+### 9.2 recovery 的默认策略
+
+默认流程应是：
+
+1. 内部先自动 recovery
+2. 在短暂窗口内静默收敛
+3. 如果成功，直接交付结果
+4. 只有在完成补偿后仍无法确认，才给用户发明确兜底说明
+
+换句话说：
+
+- `recovery` 是内部机制
+- `请重发上一条消息` 才是用户级结果
+- 中间不应默认再插一层“我正在恢复”的解释提示
+
+### 9.3 stale / 残留状态的默认策略
+
+默认流程应是：
+
+1. 内部识别 stale / 残留状态
+2. 内部清理并切到正确路由
+3. 正常继续处理用户新消息
+4. 不额外宣布“我刚清理了什么”
+
+只有当 stale 行为已经影响到用户输入是否被接收、是否必须重发时，才补用户提示。
+
+### 9.4 waiting 的默认策略
+
+waiting 场景继续保留，但边界更明确：
+
+- approval / user-input 是用户必须行动的场景，所以必须提示
+- artifact 尚未可见时，可以保留最小必要兜底，但不应扩成更厚的状态叙事
+
+## 10. 需要调整的代码面
+
+### 10.1 `bridge/src/translator.ts`
+
+目标：进一步删掉解释型状态文案，只保留最小事实型文案。
+
+重点：
+
+1. 去掉“任务状态”及等价词汇
+2. 审查 recovery / infrastructure / connection lifecycle 相关文案
+3. 只保留：
+   - 等待用户动作
+   - 明确不可确认时请重发
+   - 上一轮未稳定送达的补发说明
+   - 显式控制结果
+
+### 10.2 `bridge/src/receiver.ts`
+
+目标：把更多内部状态处理收回后台。
+
+重点：
+
+1. recovery attempt 默认静默
+2. stale active turn 清理默认静默
+3. 只有用户必须知道时，才发 `status_reply` / `error_reply`
+4. 检查现有 `status_reply` / `progress_update` 路径，逐个判断是否真的还该保留
+
+### 10.3 文档口径
+
+需要同步回写：
+
+- `README.md`
+- `docs/user-quickstart.md`
+- `docs/manual-acceptance.md`
+- `docs/planning/SPEC-session-presence-and-state-visibility.md`
+- 必要时补充 `PRODUCT.md` / `DASHBOARD.md`
+
+目标是把“bridge 是稳定桥梁，不是任务解释器”写成长期口径。
+
+## 11. 验收标准
+
+满足下面条件，才算本专题完成。
+
+### 11.1 前台默认不再暴露内部 recovery 过程
+
+1. fresh turn 的短暂 recovery 不再默认出现在用户前台
+2. 只有完整补偿后仍无法确认，才明确提示用户重发
+3. 自动化测试覆盖“内部 recovery 成功但用户前台静默”的主路径
+
+### 11.2 前台默认不再暴露内部状态清理过程
+
+1. stale / 残留状态清理不再默认发“已清理旧状态”之类提示
+2. 清理后直接进入新消息正常处理
+3. 自动化测试覆盖该路径
+
+### 11.3 用户必须行动的提示仍完整保留
+
+1. approval / user-input 相关提示不丢
+2. `/stop`、`/new`、`/takeover`、`/codex` 等控制结果不丢
+3. delivery unavailable / redelivery 相关提示不丢
+
+### 11.4 文档口径一致
+
+1. README / quickstart / manual acceptance 不再把“任务状态”当作稳定产品面
+2. presence / protocol alignment 文档明确写出“默认只转发事实，不解释内部状态”
+
+## 12. 风险 / 假设 / 待决问题
+
+### 12.1 风险
+
+1. 如果收得过猛，可能把某些用户其实仍然需要的提示也一起删掉
+2. 某些 waiting artifact pending 场景，是否还需要一条最小兜底提示，需要结合真实 Feishu 表现再判断
+3. 部分旧测试、旧文档、旧思路会和新边界冲突，需要系统性清理
+
+### 12.2 假设
+
+1. 用户真正需要知道的是“我要不要现在行动”和“结果有没有稳定回来”，而不是 bridge 内部状态机细节
+2. bridge 内部 ledger / recovery 足够支撑静默补偿，不需要靠大量中间提示维持可信度
+
+### 12.3 待决问题
+
+1. `connectionLifecycleMessage` 在 active turn 下是否也应进一步静默，还是保留极少数事实型提示
+2. waiting artifact sync pending 是否完全收回内部，还是保留单条最小兜底
+3. `completion without reply` 的结束提示是否还要继续保留现状，还是再进一步收薄

package/docs/planning/SPEC-npm-alpha-distribution-and-install-first-release.md

@@ -0,0 +1,222 @@
+# SPEC: NPM Alpha Distribution & Install-First Release Model
+
+更新时间：2026-03-31  
+状态：Draft / Ready for review  
+Owner：work-ally product / engineering  
+相关文档：
+- `docs/product-spec-standard.md`
+- `docs/planning/SPEC-local-stable-release-boundary.md`
+- `internal/modules/runtime/release.sh`
+- `README.md`
+
+## 1. Summary
+
+这份 spec 定义 `work-ally` 的发布模型切换：
+
+> 从“本机 stable release 副本”切换为“npm 包发布 + install-first 使用模型”。
+
+第一阶段明确目标：
+
+1. 先支持 `macOS arm64`（M 系列）作为首发正式目标平台。
+2. 发布通道先走 `alpha`（例如 `0.x.y-alpha.n`），用于快速迭代和真实安装验证。
+3. 用户与维护者都通过 `npm install` / `npm update` 方式使用，不再依赖 `ally release` 产出本机 stable 副本。
+
+一句话：以后“发布”= 推到 npm；“使用/自测”= 从 npm 安装。
+
+## 2. 背景
+
+当前 `work-ally` 的稳定使用路径依赖本机 release 副本：
+
+- `ally release` 会把源码树复制到 `~/.work-ally/releases/stable/`
+- 默认 `ally` 入口优先消费这个本机 stable 目录
+
+这条路径在内部打磨阶段有效，但在接近公开发布阶段存在明显问题：
+
+1. 发布与分发不统一：外部用户拿不到“标准安装路径”，仍需理解源码仓库与本地 release 概念。
+2. 维护者心智分裂：开发态、发布态、使用态不是同一条链路。
+3. 可传播性弱：无法直接用 npm 版本号和 dist-tag 管理 alpha 节奏。
+4. 验证偏差：维护者常在源码树路径下验证，和真实用户安装形态不一致。
+
+当前产品已经接近可发布阶段，分发模型需要从“本机复制”升级到“包管理器分发”。
+
+## 3. 问题定义
+
+本专题要解决四个核心问题。
+
+### 3.1 发布入口不统一
+
+当前“发布”实质是本机目录替换，不是对外分发，无法形成标准版本传播路径。
+
+### 3.2 使用入口不统一
+
+维护者可以绕过真实安装链路直接跑源码，导致“我本机可用”与“用户可安装可用”之间存在偏差。
+
+### 3.3 版本语义不统一
+
+缺少 npm 层的 alpha 版本节奏与 tag 管理，无法用标准方式表达“可试用但仍在快速迭代”。
+
+### 3.4 平台支持边界不清晰
+
+理论上 Node 脚本跨平台可跑，但当前未验证矩阵不完整。产品需要先明确首发支持边界，避免“名义支持很多、实际上不稳”。
+
+## 4. 目标 / 非目标
+
+## 4.1 目标
+
+1. 建立 npm 发布为唯一正式发布动作（至少在首发阶段）。
+2. 建立 install-first 模型：维护者和用户都通过 npm 安装包来使用 `ally`。
+3. 首发明确支持 `macOS arm64`；其他平台默认不做承诺，后续按验证逐步放开。
+4. 发布节奏默认走 `alpha` dist-tag，支持快速迭代。
+5. 用户文档明确：当前不支持用户侧定时任务，默认不会在无用户触发时后台自行跑任务。
+
+## 4.2 非目标
+
+1. 本专题不承诺 Windows 支持。
+2. 本专题不承诺 Linux 正式支持（可做探索验证，但不写入首发承诺）。
+3. 本专题不引入新的 GUI 安装器。
+4. 本专题不重做 runtime 内核或 bridge 语义。
+5. 本专题不讨论收费/授权模型。
+
+## 5. 产品定义与用户路径
+
+## 5.1 产品定义
+
+发布模型定义为：
+
+- `发布`：将 `work-ally` CLI 包发布到 npm（alpha tag）。
+- `安装`：用户通过 npm 安装包获得 `ally` 命令。
+- `升级`：用户通过 npm 更新版本。
+- `使用`：所有正式路径都基于已安装包，而非本地源码副本。
+
+## 5.2 用户路径 A（普通用户）
+
+1. 在支持平台（首发：macOS arm64）执行 npm 安装命令。
+2. 直接使用 `ally setup/start/status/...`。
+3. 新版本发布后，执行 npm 更新命令。
+
+## 5.3 用户路径 B（维护者自测）
+
+1. 在源码仓库开发与测试。
+2. 发布 alpha 到 npm。
+3. 在本机清理旧安装并从 npm 安装该 alpha 包。
+4. 用“真实安装形态”执行回归与验收。
+
+关键约束：维护者日常可在源码仓库开发，但对“发布可用性”结论必须基于 npm 安装形态。
+
+## 6. 机制设计
+
+## 6.1 发布渠道与版本语义
+
+1. npm 包采用 prerelease 版本语义（例如 `0.2.0-alpha.1`）。
+2. 首发阶段默认使用 `alpha` dist-tag 发布。
+3. 当版本达到可稳定使用标准后，再引入 `latest` 策略（不在本 spec 首期目标内强制落地）。
+
+## 6.2 入口命令与安装形态
+
+1. npm 包必须暴露标准 CLI bin：`ally`。
+2. 文档主路径统一为“安装后直接运行 `ally`”。
+3. 明确不再把 `ally release` 作为正式发布动作。
+
+## 6.3 现有本机 stable release 语义迁移
+
+1. `ally release` 直接移除，不保留兼容期。
+2. `~/.work-ally/releases/stable/` 不再作为长期主路径依赖。
+3. `ally status` 中与本机 stable release 强耦合的文案与字段需收口为“当前安装版本/来源”。
+
+## 6.4 平台支持声明
+
+1. 首发支持声明写死：`macOS arm64`。
+2. Linux 可作为“实验可用”状态，不进入正式承诺与对外口径。
+3. 文档中避免“理论可用=正式支持”的表述。
+
+## 6.5 自动化发布（一条龙）
+
+发布流程应收口成单入口自动化流水线（CI 或脚本），至少包含：
+
+1. 版本校验（alpha 语义校验）。
+2. 测试门禁（最小测试集 + 必要发布前 smoke）。
+3. npm publish 到 `alpha` tag。
+4. 发布结果回显（版本号、tag、安装命令）。
+
+这条流水线是正式发布入口；手工临时发布不作为长期主路径。
+
+## 6.6 用户侧资源消耗承诺
+
+面向用户必须明确表达：
+
+1. 当前不支持用户侧定时任务能力。
+2. 默认不会在用户无触发时自行发起任务执行。
+3. 不会因为“安装了工具”就持续后台消耗执行资源。
+
+注：内部记忆压缩等系统机制属于实现层，不作为用户“可配置定时任务”能力对外承诺。
+
+## 6.7 Core / Hybrid / Skill 分类判断
+
+本能力属于 **Core**，不是 Skill。
+
+原因：
+
+1. 它改变的是产品分发与默认使用路径，是全局主合同。
+2. 它涉及 `ally` 入口语义、发布机制、文档与状态口径，不是按需触发工作流。
+3. 若做成 Skill，会让“是否可安装可发布”依赖可选能力，破坏产品稳定边界。
+
+## 7. Scope / Phase（按用户价值）
+
+### Phase 1：NPM Alpha 首发闭环（必须）
+
+用户价值：用户可按标准 npm 路径安装并使用 `ally`，无需理解源码 release 机制。
+
+交付内容：
+
+1. npm alpha 发布可用。
+2. `ally` bin 安装后可直接运行。
+3. 首发支持声明与文档收口到 macOS arm64。
+4. `ally release` 完整下线。
+
+### Phase 2：安装与升级体验收口（建议）
+
+用户价值：用户能清楚知道如何升级、如何确认当前版本来源。
+
+交付内容：
+
+1. `ally status` 显示安装版本和渠道信息。
+2. 文档补齐升级、回滚、已知平台边界。
+3. 原本地 stable release 相关遗留说明清理完成。
+
+### Phase 3：Linux 支持评估（可选）
+
+用户价值：在不降低稳定性的前提下扩大平台覆盖。
+
+交付内容：
+
+1. Linux 兼容性验证报告。
+2. 若达标，升级支持声明；若不达标，保持“非承诺平台”并公开限制。
+
+## 8. 验收标准
+
+1. 存在可用 npm 包发布流程，且可发布 `alpha` 版本。
+2. 在 macOS arm64 上，用户可通过 npm 安装后直接运行 `ally` 主命令。
+3. 产品文档不再把 `ally release` 作为正式发布主路径。
+4. 维护者可通过“发布后再 install 验证”的方式完成真实安装链路回归。
+5. 对外文档明确写出：当前不支持用户侧定时任务，默认无触发不执行。
+6. 对外文档明确写出：首发正式支持平台为 macOS arm64。
+7. 现有与本机 stable release 强绑定的文档/状态口径已完成迁移或下线说明。
+
+## 9. 风险 / 假设 / 待决问题
+
+## 9.1 风险
+
+1. 代码与文档若清理不彻底，可能残留本机 stable release 旧口径，造成认知不一致。
+2. 若 npm 包入口与当前目录结构耦合过深，可能出现安装后路径问题。
+3. 首发只承诺 macOS arm64 可能引发 Linux 用户预期落差。
+
+## 9.2 假设
+
+1. 当前实现不依赖必须编译的本地 C/C++ 产物，可走 npm 分发主路径。
+2. 团队可提供最小 CI/自动化能力支撑 alpha 发布。
+
+## 9.3 待决问题
+
+1. npm 包名最终确定为 `work-ally-cli` 还是其他命名？
+2. npm 安装推荐形态：`npm i -g`、`npx`、还是两者并行？
+3. Linux 何时从“可探索”升级为“正式支持”？需要哪些验证门槛？