work-ally 0.2.0-alpha.1

package/docs/planning/SPEC-stable-archive-contract.md

@@ -0,0 +1,456 @@
+# Stable Archive Contract
+
+## Status
+
+- Target project: `work-ally`
+- Audience: implementation engineer / product architect
+- Scope: assistant desk raw archive under `.system/archive/`
+- Status: shipped baseline / contract pending cleanup
+- Goal: freeze the raw materials contract so future digest/compression mechanisms can evolve without rewriting history
+
+## Summary
+
+这份文档定义 `work-ally` 的稳定原材料协议，也就是 assistant desk 下 `.system/archive/` 的长期合同。
+
+当前状态补充：
+
+- `.system/archive/YYYY/MM/DD/<channel>--<conversation>.ndjson` 这条主目录结构与事件落盘能力已经进入 shipped baseline
+- 当前仍需继续收口的是：哪些事件字段属于稳定合同、哪些只属于实现细节，以及文档与现有 archive/store 行为的最终核对
+
+核心结论：
+
+1. `archive` 是 **原材料层**，不是 memory 层，也不是 digest 层。
+2. digest / compression 机制未来可以更换，但 archive 的目录结构与事件骨架应尽早冻结。
+3. archive 必须是：**append-only、可审阅、低解释、弱加工、长期稳定**。
+4. archive 的职责是忠实记录“发生了什么”，而不是替未来机制提前做总结。
+
+一句话定义：
+
+> archive = assistant 与外界交互过程的稳定原材料账本。
+
+---
+
+## Why Freeze It Now
+
+记忆提炼机制未来很可能变化：
+
+- nightly digest 可能改
+- 压缩策略可能改
+- 摘要 prompt 可能改
+- `MISTAKES.md` / `MEMORY.md` 的写法可能改
+
+但这些变化不应反过来污染原材料层。
+
+如果 archive 契约一直摇摆，会出现三个问题：
+
+1. 历史数据不可持续复用
+2. 后续 compression 机制难以兼容旧材料
+3. 用户无法相信这是一份稳定可追溯的工作账本
+
+所以当前阶段必须先冻结 archive 合同，再允许上层策略演进。
+
+---
+
+## Non-goals
+
+这份 spec 不定义：
+
+- `MEMORY.md` 如何提炼
+- `NOW.md` 如何更新
+- `MISTAKES.md` 如何组织
+- digest prompt 长什么样
+- conversation resume 机制
+
+它只定义 raw archive 自身。
+
+---
+
+## Black-box Definition
+
+这里先把“黑匣子”定义拍死。
+
+`work-ally` 里的黑匣子，不是摘要，不是压缩结果，也不是长期记忆。
+
+它的定义是：
+
+> black-box archive = assistant 与外界交互过程的完整、追加式、可追溯事实流水。
+
+这个定义里有四个关键词：
+
+- **完整**：保留人和 AI 的完整往返正文，不做语义压缩
+- **追加式**：只追加，不回写，不重排
+- **可追溯**：能还原某段时间内某个对话发生过什么
+- **事实流水**：记录发生过的事实，而不是事后的理解与总结
+
+因此 archive 不做这些事：
+
+- 不把正文提前压缩成摘要
+- 不把长期记忆提前写回原材料
+- 不为了“省空间”删掉真实对话正文
+- 不把未来可能频繁变化的内部调试对象混成主合同
+
+一句话：
+
+> archive 约束的是结构，不压缩的是内容。
+
+---
+
+## What It Stores
+
+archive v1 应保存两大类原材料。
+
+### 1. 完整消息正文
+
+这是黑匣子的主体。
+
+应保留：
+
+- 用户发来的原始文本
+- assistant 回给用户的原始文本
+- reply-to 相关文本
+- 附件的轻量元信息
+
+这里的“完整”指的是：
+
+- inbound message 的正文完整保留
+- outbound message 的正文完整保留
+- 不做语义摘要式改写
+
+### 2. 必要的过程事件
+
+除了消息正文，archive 还应保留必要的过程事实，例如：
+
+- approval requested / resolved
+- user input requested / submitted
+- turn failed / interrupted
+- routine started / finished
+- 其他对追溯链路有长期价值的关键系统事件
+
+这些事件不是聊天正文，但属于“这次交互实际发生了什么”的一部分。
+
+### What it does not store as stable main contract
+
+以下内容不应进入 archive 的稳定主合同：
+
+- 任意自由形态的 `payload`
+- 渠道 SDK 的整块 `raw` 原包
+- 会随实现重构频繁变化的临时调试结构
+
+不是因为这些内容永远没价值，而是因为它们不稳定。
+
+如果未来确实需要保留，应以 debug sidecar 或显式附属机制处理，而不是污染稳定 archive 合同。
+
+---
+
+## Storage Granularity
+
+archive 的**物理存储粒度**固定为：
+
+> 一个外部 conversation 在某一天内一个文件。
+
+这意味着：
+
+- 不是“全局一天一个总文件”
+- 不是“一个 thread 一个文件”
+- 而是“一个 `conversation` 在某一天一个 `.ndjson` 文件”
+
+原因：
+
+- conversation 是比内部 thread 更稳定的外部定位单位
+- 同一个外部 conversation 可能跨多个内部 thread / turn
+- 按 conversation + day 切文件，既方便追溯，也能避免单文件失控膨胀
+
+因此 archive 的存储维度固定为：
+
+- **主切分维度**：`conversation_id`
+- **时间切分维度**：`YYYY/MM/DD`
+- **内部追踪字段**：`thread_id` / `turn_id` 作为记录内字段保留，但不作为主分片键
+
+---
+
+## Storage Layout
+
+archive 根目录固定为：
+
+```text
+<assistant-desk>/.system/archive/
+```
+
+日期分层固定为：
+
+```text
+.system/archive/YYYY/MM/DD/
+```
+
+单个对话文件固定为：
+
+```text
+<channel>--<conversation-id>.ndjson
+```
+
+因此完整路径模式固定为：
+
+```text
+.system/archive/YYYY/MM/DD/<channel>--<conversation-id>.ndjson
+```
+
+### Stability rule
+
+以下内容视为 v1 稳定合同：
+
+- `YYYY/MM/DD` 日期目录结构
+- 每个 conversation 每天一个 `.ndjson` 文件
+- 文件名由 `<channel>--<conversation-id>` 组成
+- 文件内容为一行一个 JSON object
+
+未来如需变更，只能新增版本迁移机制，不能直接悄悄改。
+
+---
+
+## File Semantics
+
+每个 `.ndjson` 文件表示：
+
+> 某一天、某个 channel、某个 conversation 内发生的稳定可追溯事件流。
+
+要求：
+
+- append-only
+- 按发生顺序追加
+- 不做原地修改
+- 不因上层 digest 结果回写 archive
+
+archive 文件是事实流水，不是摘要文档。
+
+---
+
+## Record Model
+
+### 1. Common envelope
+
+每条记录都必须包含稳定公共字段：
+
+- `schema_version`: 当前固定为 `1`
+- `at`: ISO 8601 时间戳
+- `direction`: `inbound` | `outbound` | `system`
+- `event_type`: 稳定事件类型字符串
+- `channel`: 渠道标识
+- `conversation_id`: 对话标识
+
+这六个字段属于 archive 主合同，任何记录都不能缺。
+
+### 2. Conversation identity
+
+conversation 维度字段必须冗余写在每条记录里，而不是只依赖文件路径。
+
+原因：
+
+- 单条记录可脱离文件单独处理
+- 后续聚合与重放更稳定
+- 文件移动或抽样时不丢上下文
+
+### 3. Event payload rule
+
+公共字段之外，允许按 `event_type` 携带有限的事件字段。
+
+但不允许：
+
+- 任意形状的自由 `payload`
+- 把整块 channel SDK 原始对象作为稳定主字段
+- 把未来会频繁变化的内部调试结构混进主合同
+
+也就是说：
+
+> archive 可以有事件专属字段，但不能退化成“随便塞一个 payload”。
+
+---
+
+## Stable Event Types
+
+v1 建议固定以下事件类型。
+
+### `message_inbound`
+
+表示收到一条用户输入。
+
+稳定字段：
+
+- `message_id`
+- `sender_id`
+- `sender_name`
+- `chat_type`
+- `text`
+- `reply_to_message_id`
+- `root_message_id`
+- `reply_to_text`
+- `attachments`
+
+### `message_outbound_runtime`
+
+表示 runtime 已产出一条最终或中间结果，并由 bridge 记录。
+
+稳定字段：
+
+- `turn_id`
+- `thread_id`
+- `status`
+- `reply`
+- `reply_preview`
+- `error`
+
+### `message_outbound_channel`
+
+表示 bridge 向外部 channel 投递了一条消息。
+
+稳定字段：
+
+- `envelope_type`
+- `message_id`（如有）
+- `text`
+- `text_preview`
+
+对于审批、用户输入请求等特殊外发，允许追加有限稳定字段，但仍属于 `message_outbound_channel` 大类。
+
+### `system_event`
+
+表示非消息类系统事件。
+
+系统事件也不能使用自由 `payload`，必须继续细分稳定 `system_type`，例如：
+
+- `runtime_progress`
+- `approval_requested`
+- `approval_resolved`
+- `user_input_requested`
+- `user_input_submitted`
+- `turn_failed`
+- `turn_interrupted`
+- `routine_started`
+- `routine_progress`
+- `routine_finished`
+
+`system_event` 的稳定字段：
+
+- `system_type`
+- 与该 `system_type` 对应的有限稳定字段
+
+---
+
+## Raw Data Policy
+
+### `raw` is not part of the stable contract
+
+channel 原始对象、SDK 返回体、事件原文，可能对调试有用。
+
+但它们不应成为 archive 稳定主合同的一部分。
+
+因此 v1 建议：
+
+- 不把 `raw` 作为 archive 主合同字段
+- 如确有调试需要，单独设计 debug 开关或侧带留存机制
+- 任何 `raw` 留存都应被视为非稳定附属能力，不能成为未来 compression 的依赖前提
+
+原因：
+
+- `raw` 容易膨胀
+- `raw` 的形状受 SDK 和渠道波动影响大
+- 一旦把 `raw` 写进主合同，就很难冻结 archive 协议
+
+---
+
+## Attachments Policy
+
+附件字段 `attachments` 允许存在，但只保留稳定、轻量、可长期理解的元信息，例如：
+
+- `kind`
+- `name`
+- `token`
+- `path`
+
+不在 archive 主合同中承诺：
+
+- 附件二进制本体
+- 渠道私有的复杂附件结构
+- 长期不稳定的解析结果
+
+---
+
+## Ordering And Mutability
+
+### Ordering
+
+同一文件中的记录应按追加顺序排列，默认近似代表事件发生顺序。
+
+允许出现轻微时间交错，但禁止后写覆盖前写。
+
+### Mutability
+
+archive 一旦写入，默认不可改。
+
+禁止：
+
+- digest 回写 archive
+- nightly compact 改写历史记录
+- 为了“看起来更整洁”重排历史
+
+如果未来出现修复需求，应采用：
+
+- 新增修正记录
+- 或在明确迁移工具下整体迁移版本
+
+而不是直接 silent edit。
+
+---
+
+## Read Expectations
+
+archive 的典型消费者包括：
+
+- nightly digest / future compression
+- 人工排障
+- 历史审计
+- 未来的记忆提炼机制
+
+如果目标是“看完整聊天链路”而不是“核对底层事实”，优先应使用 `conversations/` 视图层，而不是直接扫描 raw archive。
+
+archive 默认不是：
+
+- assistant 启动热路径必读材料
+- 用户日常编辑文件
+- 长期记忆正文
+
+原因很直接：
+
+- raw archive 必然包含一定过程噪音
+- 它追求的是稳定与完整，不是最优阅读体验
+- 适合阅读的问题，应交给上层 view layer 处理，而不是强迫 raw layer 同时兼顾“好读”和“稳定”
+
+因此产品分层明确为：
+
+- `archive`：稳定原材料层
+- `conversations/`：可读视图层
+- `SOUL.md` / `NOW.md` / `MISTAKES.md` / `MEMORY.md`：热路径与沉淀层
+
+---
+
+## Acceptance Criteria
+
+archive contract 进入可实施状态，至少满足：
+
+1. 路径结构固定为 `.system/archive/YYYY/MM/DD/<channel>--<conversation-id>.ndjson`
+2. 每条记录都有稳定公共头：`schema_version` / `at` / `direction` / `event_type` / `channel` / `conversation_id`
+3. 不再使用自由形态 `payload` 作为稳定主字段
+4. `raw` 不再属于 archive 稳定主合同
+5. 事件类型集合被显式命名并收敛
+6. archive 保持 append-only，不被 digest 或回写流程修改
+7. 上层 memory / compression 机制可以演进，但不需要重定义 archive
+
+---
+
+## Implementation Notes
+
+基于当前实现，下面两点需要在实现阶段重点修正：
+
+1. 当前 archive 记录里存在 `raw` 字段，应从稳定主合同移除或降级为非稳定调试能力
+2. 当前 `system` 事件使用自由 `payload`，应改成稳定 `system_type` + 限定字段模型
+
+如果这两点不处理，archive 还不能算真正冻结。

package/docs/planning/SPEC-supervised-start-boundary.md

@@ -0,0 +1,127 @@
+# SPEC: 受管 AI 环境下的后台启动边界
+
+状态：Draft / Ready for implementation
+更新时间：2026-03-14
+
+## 背景
+
+当前 `work-ally` 支持在普通终端中通过 `ally start` / `ally restart` 拉起后台 `supervisor`、`bridge`、`runtime-host` 与 `assistant-autosave`。
+
+但在真实使用中出现了一个高价值问题：
+
+- 维护者或另一个 AI 在受管执行环境里代用户执行 `ally start`
+- 命令当下返回成功
+- 日志里也能看到 `ws_started`、`work-ally started`
+- 但宿主执行环境结束后，后台进程很快被一起回收
+- 飞书用户与开发者后台随后表现为“像是启动过，但其实已经没在跑”
+
+这会造成一种比直接失败更糟糕的体验：**伪成功**。
+
+## 问题定义
+
+当前缺口不是“后台服务没法启动”，而是：
+
+1. 产品没有明确区分“用户自己的持久终端”与“AI/受管执行环境”
+2. `ally start` 在不可靠宿主环境里仍然尝试后台化，并给出成功反馈
+3. `ally status` 虽已有 stale 检测，但对首次使用者仍然太晚
+
+## 目标
+
+1. 禁止在受管 AI 执行环境里默认后台启动并返回伪成功
+2. 把“后台常驻必须由用户自己的终端承担”收成明确产品边界
+3. 对用户给出短、准、可执行的错误提示
+4. 不破坏前台模式和现有正常终端启动路径
+
+## 非目标
+
+- 不实现桌面守护进程安装器
+- 不在本次解决跨登录会话常驻
+- 不把中间层做成系统级 launch agent
+- 不阻止普通 shell / iTerm / Terminal 中的正常后台启动
+
+## 核心判断
+
+### 1. 受管 AI 执行环境不应被视为可靠后台宿主
+
+如果当前进程运行在明显的受管 AI 执行环境中，例如存在 `CODEX_THREAD_ID` / `CODEX_CI=1` 这类标记，则默认不应把后台服务的长期存活建立在该宿主上。
+
+### 2. 失败要早于“看起来成功”
+
+与其让用户几分钟后在飞书或状态页看到 stale，不如在 `ally start` 当下就直接拒绝，并说明：
+
+- 当前环境不适合后台启动
+- 请回到你自己的终端执行
+
+### 3. foreground 例外保留
+
+若显式使用 `WORK_ALLY_FOREGROUND=1`，说明调用方知道自己在前台接管服务生命周期，此时不应拦截。
+
+## 方案
+
+### 1. 增加受管环境检测
+
+在 shell 层增加一个最小检测函数，例如：
+
+- 命中 `CODEX_THREAD_ID`
+- 或 `CODEX_CI=1`
+
+命中后视为“受管 AI 执行环境”。
+
+### 2. 后台启动保护
+
+在 `internal/modules/runtime/start.sh` 中：
+
+- 若 `WORK_ALLY_FOREGROUND != 1`
+- 且当前命中受管 AI 执行环境
+- 则直接失败，不进入后台启动流程
+
+建议提示语义：
+
+- 当前环境不适合托管长期后台服务
+- 请在你自己的终端里执行 `ally start`
+- 若只想临时前台联调，可显式使用前台模式
+
+### 3. `restart` 继承同样保护
+
+`restart` 通过 `stop.sh + start.sh` 实现，因此无需额外重复实现；只要 `start.sh` 生效即可。
+
+### 4. 文档同步
+
+至少同步：
+
+- `docs/user-quickstart.md`
+- `docs/troubleshooting.md`
+- `docs/manual-acceptance.md`
+
+文档要讲清楚：
+
+- AI 可以帮你改代码、查问题
+- 但真正需要长期常驻的 assistant，最好由用户自己的终端执行 `ally start`
+- 若在受管执行环境中尝试后台启动，产品会直接拒绝，避免伪成功
+
+## 验收标准
+
+1. 在普通终端中执行 `ally start`，现有后台启动路径不受影响
+2. 在受管 AI 执行环境中执行 `ally start`，后台模式会直接失败
+3. 失败文案明确提示“请在你自己的终端执行”
+4. `WORK_ALLY_FOREGROUND=1 ally start` 仍可用于前台运行 / 联调
+5. shell 回归覆盖上述分支
+6. quickstart 与 troubleshooting 明确写出这一边界
+
+## 风险与取舍
+
+### 风险 1：环境识别是启发式的
+
+是的，但这比继续允许伪成功更可控。V1 只抓最明确的 Codex 受管标记，不做泛化过度识别。
+
+### 风险 2：会让 AI 代启动能力受限
+
+这是刻意收边界。能改代码、不代表适合作为长期后台进程宿主。
+
+## 结论
+
+本期把这件事定义为产品边界，而不是用户自己总结经验：
+
+- 受管 AI 环境不默认承担后台常驻
+- `ally start` 在该环境下直接拒绝后台模式
+- 用户回到自己的终端启动，才是可信路径