work-ally 0.2.0-alpha.1

package/docs/implementation/work-ally-implementation-guide.md

@@ -0,0 +1,790 @@
+# `work-ally` 实施指南
+
+> 当前已落地实现以 **assistant desk（办公桌）** 为中心。
+>
+> 当前 shipped model：
+> - `ally setup <name> --workspace <path>` 负责创建并初始化 assistant desk，并显式绑定项目
+> - `ally start --assistant <name>` / `ally status --assistant <name>` / `ally stop --assistant <name>` 可在任意目录显式操作目标 assistant
+> - assistant desk 默认位于 `~/.work-ally/assistants/<name>/`
+> - 办公桌根目录保存 assistant 可见资产：`AGENTS.md`、`SOUL.md`、`NOW.md`、`MEMORY.md`、`MISTAKES.md`、`journal/`、`conversations/`
+> - `.system/` 保存内部运行资产：`config.env`、`codex-home/`、`runtime/`、`logs/`、`runs/`、`cache/`、`routines/`、`archive/`
+> - 项目目录默认不再生成 `.work-ally/` 运行态，也不默认承载 assistant 长期记忆
+> - 项目只负责自己的代码与项目级规则；assistant 进入项目工作，但不拥有项目本体
+> - assistant desk 根目录默认初始化为独立 Git 仓库，并由产品层自动 checkpoint / 可选 push
+>
+> 因此，若后文仍出现早期的“项目内 `.work-ally/.env`、项目内 `memory/daily` / `memory/long-term`、`work-ally.workspace.yaml` 承载长期记忆映射”等表述，应以本节描述的**当前 shipped model**为准。
+
+
+## 0. 文档定位
+
+这份文档不是方案提案，而是**交付给实施者的执行文档**。
+
+它属于过程性文档：
+
+- 可以保留阶段、专题、DoD、实施顺序与演进痕迹
+- 但不能把已经失效的现状继续写成当前系统模型
+- 如遇“历史阶段描述”和文档顶部 shipped model 冲突，一律以前者为历史、以后者为现状
+
+它与灯塔文档 `codex-feishu-bridge-proposal.md`（位于 `../architecture/`）的关系必须明确：
+
+- `codex-feishu-bridge-proposal.md` 是**灯塔文档**，负责说明第一性原理、架构边界、目标与取舍。
+- `work-ally-implementation-guide.md` 是**实施指南**，负责把完整产品拆成可逐章推进、可逐章验收的实施阶段。
+- 实施过程中如果发现当前做法与灯塔文档冲突，**不能偷偷偏航**；要么先更新灯塔文档，要么把冲突显式记录为待决问题。
+- 只有当本指南的全部阶段 DoD 完成，且 `codex-feishu-bridge-proposal.md` 中的验收标准成立时，才可以对外宣布：**产品开发完成**。
+
+这份文档的使用对象包括：
+
+- 负责实现 `work-ally` 产品、交付 `ally.sh` 门面的工程师
+- 负责协助实现的 coding agent
+- 负责看进度、对齐阶段、做阶段验收的人
+
+它的目标不是讲概念，而是回答三件事：
+
+1. 先做什么
+2. 后做什么
+3. 什么时候算真的做完
+
+---
+
+## 1. 全局实施原则
+
+在所有阶段里，都必须同时遵守下面这些原则。
+
+### 1.1 产品边界原则
+
+- 一个工作空间就是一个助手，不在单实例内部再造多助手、多角色、多组抽象。
+- `ally.sh` 只是编排层与交互层，**官方 Codex runtime 才是唯一的大脑**。
+- `ally.sh` 不重写 agent loop，不重写推理引擎，不维护第二套模型配置。
+- IM 入口与远程文档产物表面必须分离；前者负责对话，后者负责长文呈现。
+
+### 1.2 资产与运行态分离原则
+
+- 项目长期资产留在项目本身；assistant 长期资产留在 assistant desk 或官方 Codex 家目录中。
+- assistant desk 下的 `.system/` 是**可替换运行态**，不是长期资产仓库。
+- 记忆、对话、规则、主动任务定义、黑匣子原材料与长期成果都必须在项目或 desk 的可见层可迁移、可备份。
+- 删除实现缓存后，应能重新恢复；删除整个产品实现仓库后，也应能重新接回同一个项目与 assistant desk 绑定。
+
+### 1.3 文件优先原则
+
+- 第一选择是文本文件与可人工查看的目录结构，而不是数据库。
+- session、run、archive、memory 都应尽量以 JSON / Markdown / YAML 落地。
+- 所有关键状态都应当“人能看懂、人能修复、人能 diff”。
+
+### 1.4 抽象边界原则
+
+- 架构层不把渠道名字写进抽象名。
+- `Channel Adapter`、`Runtime Client`、`Scheduler`、`Archive Store` 等都应保持供应商无关命名。
+- `Feishu`、远程文档平台、远程 MCP 只出现在实现层。
+- 当前只实现一种 IM 通道并不矛盾，但抽象层必须提前隔离好。
+
+### 1.5 TDD 与阶段验收原则
+
+- 每个阶段都必须有自己的自动化验证与人工验收动作。
+- 先写契约、夹具、假实现，再接真实外部系统。
+- 先完成小范围稳定闭环，再向更真实的外部集成推进。
+- 未通过本阶段 DoD，不进入下一阶段主线开发。
+
+### 1.6 安全默认原则
+
+- 缺少 Feishu 凭据或关键配置时，系统应**失败关闭**，不能“先跑起来再说”。
+- 默认不额外限制发送者；如果配置了 allowlist，则只服务白名单授权对象。群聊仅依赖飞书平台正确配置后的显式 `@` 机器人消息，不额外支持控制命令或 reply assistant 触发。
+- 默认不暴露公网入口，优先走个人电脑上的长连接模式。
+- 默认最小权限，尤其是远程文档写入能力必须受明确范围限制。
+
+### 1.7 进度对齐原则
+
+这份文档要能直接用于多人协作或人与 agent 协作时的进度同步，因此后续所有进度汇报都应以“阶段”为单位。
+
+标准进度汇报格式建议统一为：
+
+- 当前阶段
+- 本阶段已完成事项
+- 本阶段未完成事项
+- 当前阻塞
+- 下一条验证动作
+
+---
+
+## 2. 完整实施地图
+
+## 2.1 当前实施进度看板
+
+| 阶段 | 状态 | 说明 |
+| --- | --- | --- |
+| Stage 0 | 已完成 | 灯塔文档、实施指南、协作边界已经建立 |
+| Stage 1 | 已完成 | `work-ally/` 实现仓库骨架、测试地基与开发合同已建立 |
+| Stage 2 | 已完成 | `ally.sh`、assistant desk bootstrap、update、恢复路径已经成立 |
+| Stage 3 | 已完成 | Bridge Core、session、archive、fake channel、fake runtime 已跑通 |
+| Stage 4 | 已完成 | 当前 IM adapter、reaction 即时 ack、格式化与 allowlist 已落地；真实 Feishu 联调已跑通 |
+| Stage 5 | 已完成 | 官方 Codex Runtime 已接入，并通过真实 `codex app-server` 探针验证 |
+| Stage 6 | 已完成 | 连续 thread、`/new` 上下文切换、审批、停止、恢复、状态编排已落地 |
+| Stage 7 | 已完成 | routine、scheduler、run 记录、nightly memory digest 已落地 |
+| Stage 8 | 已完成 | Feishu Remote MCP 已改为 Codex 直连路线；`work-ally` 仅保留薄的 MCP 安装/检查封装与默认只读策略 |
+| Stage 9 | 已完成 | update、重建恢复、前台服务模式、排障文档已落地；生命周期按工作空间归属收口 |
+| Stage 10 | 已完成 | 真人验收、交接文档、黑匣子复盘路径与交付口径已经收口 |
+
+截至 2026-03-15，第一阶段已经完成，当前稳定结论只保留这些：
+
+- `cd work-ally && npm test` 通过
+- `cd work-ally && npm run test:maintainer` 通过
+- 真实 Codex Runtime + Feishu IM 闭环已完成
+- 真实 Feishu Remote MCP 只读 / 显式写回边界已完成
+- 生命周期、channel lock、全局实例可观测性、日志时间线与黑匣子契约已收口
+- 用户主入口、维护者文档、人工验收路径已经统一到 `ally` 与 `docs/` 交付面
+- assistant desk memory system v1 已收口：`SOUL.md` / `NOW.md` / `MEMORY.md` / `MISTAKES.md` / `journal/` / `conversations/`
+- archive raw layer 与 conversation view layer 已分层；稳定原材料在 `.system/archive/`，可读聊天链路在 `conversations/`
+- 会话降噪与忙时输入门控、自测默认授权、中间层异常透明化三条近期体验专项已落地并通过自动化回归
+- runtime recovery 专项已进入终态对账主路径：bridge 会主动对账 turn 终态，并在上一轮结果已产生但未稳定送达时优先自动补发
+
+### 2.2 Stage 10 收口结果
+
+Stage 10 已按三批收口：
+
+- **A 批：当前 IM 主闭环** 已通过
+- **B 批：远程文档闭环** 已通过
+- **C 批：交接与恢复闭环** 已通过
+
+因此，第一阶段当前不再保留“待执行”的人工验收分批计划。
+
+### 2.3 非阻塞但必须记住的产品注意点
+
+这些点当前不阻塞 Stage 10 收尾，但必须继续守住：
+
+- **上下文与 compaction 继续坚持 Runtime 原生优先**
+  - 已通过 `codex app-server generate-json-schema --experimental` 确认协议侧存在 `thread/tokenUsage/updated`、`thread/compact/start` 与 `contextCompaction` / `thread/compacted` 原语
+  - 这说明 Codex 侧已经有“上下文占用 / 主动 compact”的原生表面；ally 不需要自造本地 token 估算器或压缩器
+  - 当前版本先不新增 `/context` 或 `/compact`；如果未来要做，只能做对 Runtime 原生能力的薄透传
+- **`/status` 已经收敛为桥接层合理 UX**
+  - 当前固定分成 `Thread` / `Turn` / `Queue` / `Recent` / `Runtime` 五段
+  - 后续可以继续微调排版，但不要把 bridge 继续做成 dashboard 系统
+- **实施文档继续保持瘦身**
+  - 保留阶段、DoD、关键决策变化与验收口径
+  - 删除纯过程噪音，但保留关键历史拐点，方便未来回溯
+
+下面这张地图用于总览全产品的实施顺序。
+
+| 阶段 | 章节主题 | 核心结果 | 前置依赖 |
+| --- | --- | --- | --- |
+| Stage 0 | 开工合同与验收基线 | 灯塔、实施、测试、协作合同统一 | 方案方向已确定 |
+| Stage 1 | 实现仓库骨架与开发地基 | 仓库结构、工具链、测试地基成立 | Stage 0 |
+| Stage 2 | 门面、Bootstrap 与运行态外壳 | `ally.sh` 与 assistant desk 初始化闭环成立 | Stage 1 |
+| Stage 3 | Bridge Core 与假闭环 | 核心事件流、session、archive 在本地跑通 | Stage 2 |
+| Stage 4 | 当前 IM 实现接入 | 当前 IM 通道真实收发、即时回执成立 | Stage 3 |
+| Stage 5 | 官方 Codex Runtime 集成 | 真实 Runtime 闭环成立 | Stage 4 |
+| Stage 6 | 连续对话、审批与恢复 | thread 连续性、审批、停止、恢复成立 | Stage 5 |
+| Stage 7 | 主动能力与记忆闭环 | routine、scheduler、nightly digest 成立 | Stage 6 |
+| Stage 8 | Codex 直连远程文档能力 | Feishu 文档能力由 Codex 直接通过 Remote MCP 使用，`work-ally` 只保留薄封装 | Stage 7 |
+| Stage 9 | 运维、安全与交付封装 | 更新、常驻、硬化、排障与重建流程成立 | Stage 8 |
+| Stage 10 | 发布验收与完工出门 | 完整产品通过最终验收，可宣布完成 | Stage 9 |
+
+这张地图有两个硬规则：
+
+- 不能跳过前置依赖，直接把后面的复杂特性硬接进来。
+- 一个阶段的 DoD 不通过，下一个阶段就只能做预研，不能算正式推进。
+
+---
+
+## 3. Stage 0：开工合同与验收基线（已完成）
+
+### 3.1 目标
+
+把“怎么做、做到什么算完成、文档以谁为准”在真正写代码前一次说清。
+
+### 3.2 范围
+
+本阶段不追求可运行功能，只建立完整产品实施的共同基线。
+
+### 3.3 依赖
+
+- `codex-feishu-bridge-proposal.md` 已达到可作为灯塔的状态
+- 产品工作名、核心边界与核心思路已经稳定
+
+### 3.4 实施任务
+
+- 确认 `codex-feishu-bridge-proposal.md` 是唯一灯塔文档。
+- 创建并维护本实施指南，作为后续工程执行与进度对齐文档。
+- 在计划中的实现仓库根目录准备 `AGENTS.md` 与 `CLAUDE.md`，并保持二者内容一致。
+- 明确实现仓库与工作空间的分工：
+  - 实现仓库负责 `work-ally` 产品本身。
+  - 工作空间负责身份、记忆、知识、archive 与 routines。
+- 明确产品完成定义：全部阶段 DoD 通过 + 灯塔文档验收标准通过。
+- 明确阶段验收方法：自动化验证、组件集成验证、人工端到端验收三级并存。
+- 明确“当前 IM 通道实现”和“未来可扩展通道”之间的边界，不把当前实现写死到抽象层里。
+
+### 3.5 验证与测试
+
+- 检查灯塔文档与实施指南之间没有互相打架的表述。
+- 检查 `AGENTS.md` / `CLAUDE.md` 的职责是否面向实施者，而不是面向最终用户。
+- 检查文档是否已经清楚写明：用户长期资产不留在产品内部目录。
+
+### 3.6 DoD
+
+- 实施者只看这两份文档，就能知道“为什么做、先做什么、做到哪里才算完工”。
+- 后续每一阶段都有明确前置依赖、测试要求与出门条件。
+- 没有再使用 “MVP / 最小实施 / 先随便做一个” 这样的项目目标表述。
+
+---
+
+## 4. Stage 1：实现仓库骨架与开发地基（已完成）
+
+### 4.1 目标
+
+把真正可开发、可测试、可逐步交付的实现仓库地基立起来。
+
+### 4.2 范围
+
+本阶段建立仓库结构、脚手架、测试骨架、夹具与基础文档，但不要求真实接通 IM 与 Runtime。
+
+### 4.3 依赖
+
+- Stage 0 完成
+
+### 4.4 实施任务
+
+- 当前阶段的实现放在本仓库下的 `work-ally/` 目录中；后续如需独立迁出，保持该目录可整体移动。
+- 建立实现仓库目录骨架，至少包含：
+  - `ally.sh`
+  - `internal/`
+  - `bridge/`
+  - `templates/`
+  - `skills/`
+  - `tests/` 或等价测试目录
+- 在根目录建立 `AGENTS.md` 与 `CLAUDE.md`，内容一致。
+- 在 `bridge/` 下建立 TypeScript 工程、构建脚本、测试脚本与最小入口文件。
+- 在 shell 层建立最小脚本骨架：
+  - `internal/dispatch.sh`
+  - `internal/modules/bootstrap/`
+  - `internal/modules/config/`
+  - `internal/modules/runtime/`
+  - `internal/modules/routines/`
+  - `internal/modules/ops/`
+- 准备最小模板文件：
+  - `templates/env.example`
+  - `templates/work-ally.workspace.example.yaml`
+  - `templates/routines/*.yaml`
+- 准备测试夹具：
+  - fake workspace fixture
+  - fake inbound message fixture
+  - fake runtime event fixture
+  - routine fixture
+- 约定统一测试入口，至少能分成：
+  - shell 语法/静态校验
+  - bridge 单元测试
+  - bridge 集成测试
+- 在 `README.md` 中写清当前仓库是实现仓库，不是用户工作空间。
+
+### 4.5 验证与测试
+
+- 运行 shell 语法检查，例如 `bash -n` 覆盖门面与内部脚本。
+- 运行 bridge 的最小测试命令，确认测试框架与构建框架成立。
+- 在空目录 clone 后，能够安装依赖并跑通最小测试。
+
+### 4.6 DoD
+
+- 仓库可以被一个新的实施者 clone 下来并直接开始开发。
+- 根目录文档已经清楚区分“实现仓库”和“用户工作空间”。
+- 测试基础设施已可用，后续阶段不需要重新搭地基。
+
+---
+
+## 5. Stage 2：门面、Bootstrap 与运行态外壳（已完成）
+
+### 5.1 目标
+
+让 `ally` / `ally.sh` 这一层门面入口成立，并让 assistant desk 的初始化、更新与重建路径成立。
+
+### 5.2 范围
+
+本阶段聚焦 shell 门面与本地运行态外壳，不要求 Bridge Core 已接通真实通道。
+
+### 5.3 依赖
+
+- Stage 1 完成
+
+### 5.4 实施任务
+
+- 实现根门面 `ally.sh`，保持极薄，只做：
+  - 定位当前项目根目录
+  - 解析 assistant 名称与目标 desk
+  - 转发命令给 `internal/dispatch.sh`
+- 实现 `internal/dispatch.sh` 路由，不把业务逻辑堆到门面中。
+- 实现 `setup / help / start / stop / restart / status / logs / update / routine ...` 的基础分发。
+- 实现 `internal/modules/bootstrap/setup.sh`：
+  - 初始化 `~/.work-ally/assistants/<name>/`
+  - 生成 assistant desk 的可见骨架：`AGENTS.md`、`SOUL.md`、`NOW.md`、`MEMORY.md`、`MISTAKES.md`、`journal/`、`conversations/`
+  - 初始化 `.system/config.env`、`.system/codex-home/`、`.system/runtime/`、`.system/logs/`、`.system/runs/`、`.system/cache/`
+  - 初始化 assistant / project registry，并记录项目到 assistant 的绑定
+  - 在 desk 根目录执行独立 `git init`，为后续自动 checkpoint 做准备
+- 实现 `internal/modules/config/`，把 assistant desk 内部运行配置与项目现场彻底分开。
+- 实现 `update` 路径：
+  - 更新产品内部实现
+  - 不覆盖 assistant 已生成的长期记忆与对话资产
+  - 不重新发明用户的模型配置
+- 明确项目目录不再承载 assistant 运行态；项目只作为工作现场被挂载使用。
+- 明确 `.system/config.env` 的角色：只描述 assistant desk 的本地 bridge/runtime 配置。
+
+### 5.5 验证与测试
+
+- 在临时工作空间连续执行多次 `ally setup`，验证幂等性。
+- 手动删除实现缓存后重新运行 `ally setup` 或 `ally update`，验证可恢复。
+- 验证当 Feishu 凭据或关键配置缺失时，`start` 应明确失败而不是含糊启动；allowlist 留空时应允许启动。
+- 验证已有工作空间中的 `AGENTS.md`、记忆、知识、归档文件不会被 `setup` 覆盖。
+
+### 5.6 DoD
+
+- 用户只需要理解一个入口：`ally <command>`。
+- assistant desk 的初始化、状态目录与恢复路径已经成立。
+- 产品内部实现与工作空间资产已经被结构性分开。
+
+---
+
+## 6. Stage 3：Bridge Core 与假闭环（已完成）
+
+### 6.1 目标
+
+先不接真实外部系统，把 Bridge 的核心事件流、会话台账与黑匣子归档在本地跑通。
+
+### 6.2 范围
+
+本阶段实现 Bridge Core、自定义契约、fake channel、fake runtime，不接真实 IM 与真实 Codex Runtime。
+
+### 6.3 依赖
+
+- Stage 2 完成
+
+### 6.4 实施任务
+
+- 定义统一的 channel contract，至少覆盖：
+  - `conversation_ref`
+  - `inbound_message`
+  - `ack_received`
+  - `progress_update`
+  - `approval_requested`
+  - `approval_resolved`
+  - `final_reply`
+  - `stop_requested`
+- 实现 `bridge/src/receiver.ts`，把标准化入站事件送入后续流程。
+- 实现 `bridge/src/translator.ts`，把 runtime 事件翻译为统一的对外语义。
+- 实现 `bridge/src/session-store.ts`：
+  - conversation -> thread 映射
+  - `meta.json`
+  - `current-thread.json`
+  - `turns/*.json`
+  - `approvals/*.json`
+  - `events.ndjson`
+- 会话原材料采集已演进为按 `thread/read(includeTurns=true)` 的 thread-sync 快照写入（`bridge/src/thread-sync.ts`）。
+- 实现 fake runtime：
+  - 能模拟进度事件
+  - 能模拟审批事件
+  - 能模拟最终回复
+- 实现 fake channel adapter：
+  - 输入标准消息
+  - 接收标准回包
+- 为后续真实 IM 和真实 Runtime 预留相同接口。
+
+### 6.5 验证与测试
+
+- 编写单元测试覆盖 session-store 的文件读写与恢复。
+- 编写单元测试覆盖 translator 的事件翻译。
+- 编写集成测试：fake inbound message -> receiver -> fake runtime -> translator -> fake outbound reply。
+- 编写集成测试验证 archive 文件是否稳定落盘。
+
+### 6.6 DoD
+
+- 不接真实外部系统，Bridge Core 也能完整走通一次假闭环。
+- `.system/runtime/sessions/`、`.system/archive/` 与 `conversations/` 的职责边界已经稳定、可读、可人工检查。
+- 失败、审批、进度三类事件在 Core 层已经有一致语义。
+
+---
+
+## 7. Stage 4：当前 IM 通道实现接入（已完成）
+
+### 7.1 目标
+
+把当前 IM 通道真实接入进来，让用户真的能发消息、收到即时回执、再收到结果回复。
+
+### 7.2 范围
+
+本阶段只实现**当前 IM 通道**的真实适配层，不把通道特有逻辑污染到 Bridge Core。
+
+### 7.3 依赖
+
+- Stage 3 完成
+
+### 7.4 实施任务
+
+- 在 `bridge/src/channels/<current-impl>/` 下实现当前 IM adapter。
+- 实现长连接接入方式，避免依赖公网回调地址。
+- 实现基础验签、消息识别、事件去重与最小异常处理。
+- 实现 1:1 使用边界与 allowlist 校验。
+- 实现 **Immediate Ack**：
+  - 消息一进入系统，在通过最小校验后立即给出 reaction 级回执
+  - 让用户立刻知道“消息已收到”
+- 实现消息格式化层：
+  - Markdown 转通道展示格式
+  - 表格/长文拆分
+  - 文本降级与安全截断
+- 借鉴 `nanobot` 中已被验证过的行为，但不要把它的整体架构搬进来。
+- 保持 Core 层仍只依赖标准 channel contract。
+
+### 7.5 验证与测试
+
+- 为格式化器编写测试，覆盖 Markdown、表格拆分、长文本拆分。
+- 为 adapter 编写测试，覆盖授权用户、未授权用户、重复消息、异常消息、Immediate Ack 与长消息拆分。
+- 人工真实联调一次：
+  - 发出消息
+  - 立即收到回执
+  - 收到正式回复
+- 验证全流程不需要公网地址、域名或回调 URL。
+
+### 7.6 DoD
+
+- 当前 IM 通道可以稳定收消息、回 Ack、发结果。
+- 未授权对象会被稳定拒绝。
+- 通道逻辑没有反向污染 Core 抽象。
+
+---
+
+## 8. Stage 5：官方 Codex Runtime 集成（已完成）
+
+### 8.1 目标
+
+把真实的官方 Codex Runtime 接入进来，让 `work-ally` 真正围绕官方大脑工作。
+
+### 8.2 范围
+
+本阶段只做 Runtime 集成，不重新解释或接管官方 Codex 的模型配置、认证与提示词体系。
+
+### 8.3 依赖
+
+- Stage 4 完成
+
+### 8.4 实施任务
+
+- 实现 `bridge/src/runtime-client.ts`，对接 `codex app-server`。
+- 明确官方 Codex runtime 的启动契约：
+  - 与 `work-ally` 在同一系统用户上下文运行
+  - 共享同一个 HOME
+  - 共享官方 Codex 可见的环境变量与认证上下文
+- 由 `work-ally` 负责：
+  - 检查 `codex app-server` 是否可启动
+  - 启动、停止、健康检查与日志管理
+- 明确 `work-ally` 不负责：
+  - 解析 `~/.codex/config.toml` 的业务含义
+  - 复制 API key 到自己的 `.env`
+  - 发明第二套模型/provider 配置
+  - 重写官方系统提示或运行循环
+- 实现 Runtime 事件映射：
+  - 普通回复
+  - 进度
+  - 审批
+  - 错误
+  - 停止
+- 确保所有正式对话都进入官方 Runtime，而不是桥接层自己假装在思考。
+
+### 8.5 验证与测试
+
+- 对 `runtime-client.ts` 编写接口层测试，覆盖 thread 创建、消息发送、事件流处理。
+- 在本机环境做 healthcheck smoke test，确认 `codex app-server` 可被拉起并可响应。
+- 执行一条真实 IM 消息 -> 真实 Runtime -> 真实回复的人工联调。
+
+### 8.6 DoD
+
+- 当前 IM 消息已经由真实官方 Runtime 处理并给出正式回复。
+- `ally.sh` 没有长出第二套模型配置与 agent loop。
+- Runtime、工作空间与用户本地官方 Codex 环境三者边界清晰。
+
+---
+
+## 9. Stage 6：连续对话、审批与恢复（已完成）
+
+### 9.1 目标
+
+让远程使用不只是“发一次消息拿一次回复”，而是真正具备连续 thread、审批闭环、长任务观察与基础恢复能力。
+
+### 9.2 范围
+
+本阶段补齐使用连续性与运行恢复，不引入主动任务调度。
+
+### 9.3 依赖
+
+- Stage 5 完成
+
+### 9.4 实施任务
+
+- 建立稳定的 conversation -> thread 绑定规则。
+- 实现命令语义：
+  - `/new`
+  - `/status`
+  - `/approve`
+  - `/deny`
+  - `/stop`
+- 实现审批记录与审批回传。
+- 实现长任务阶段性进度摘要与消息回送。
+- 完善 `session-store.ts` 的 turn 生命周期记录。
+- 实现 `start / stop / status / restart` 的真实进程编排。
+- 实现恢复语义：
+  - 识别陈旧 pid / lock
+  - Runtime 活、Bridge 死时只补 Bridge
+  - Bridge 活、Runtime 死时先修 Runtime
+- 保留日志、session 与审批台账，不在停止时顺手清空历史。
+
+### 9.5 验证与测试
+
+- 编写集成测试覆盖 `/new`、审批流、停止流。
+- 编写恢复测试，模拟 Bridge 进程死掉、Runtime 进程死掉、pid 残留等情况。
+- 人工联调：
+  - 在同一会话中连续对话
+  - 触发一次审批
+  - 处理中途停止
+  - 重启后继续工作
+
+### 9.6 DoD
+
+- 同一个远程会话能够连续工作，而不是每次都像第一次见面。
+- 高风险动作可以进入审批闭环。
+- 进程异常、重启、残留状态都有可解释的恢复路径。
+- `/new`、`/status`、`/approve`、`/deny`、`/stop` 已有自动化回归覆盖。
+- `/status` 不是只看本地 thread 绑定；它还会优先读取 Runtime 原生状态（`thread/read`，并可被 `thread/status/changed` 缓存兜底）。
+- runtime 断连恢复语义继续坚持薄桥接：bridge 只在有限窗口内确认 turn 是否已完成，无法确认时明确要求用户重发，而不自造厚重的任务续跑系统。
+
+---
+
+## 10. Stage 7：主动能力与记忆闭环（已完成）
+
+### 10.1 目标
+
+把 `work-ally` 从“被动回复”推进到“能主动做事”，并建立原材料 -> 每日记忆 -> 长期记忆的闭环。
+
+### 10.2 范围
+
+本阶段实现 routines、scheduler、run 记录、nightly memory digest 与相关技能装配点。
+
+### 10.3 依赖
+
+- Stage 6 完成
+
+### 10.4 实施任务
+
+- 实现 `routines_path` 任务定义契约，推荐 YAML。
+- 实现 `routine list / run / enable / disable` 命令。
+- 实现 `bridge/src/scheduler.ts`：
+  - 扫描 routine 定义
+  - 合并本地启停覆盖
+  - 计算下一次触发点
+  - 做 dedupe、防重、busy 保护
+- 实现 assistant desk `.system/runtime/routines-state.json`。
+- 实现 assistant desk `.system/runs/` 记录：
+  - `latest.json`
+  - 按次落盘的 run 记录
+- 实现主动执行时的 thread 选择语义：`reuse` / `new`。
+- 实现 `writeback` 的第一批安全能力：
+  - `append_markdown`
+  - `none`
+- 实现 `push` 的第一批能力：
+  - `none`
+  - 推送到默认 IM 目标
+- 实现 nightly `memory-digest`：
+  - 原材料只来自自动沉淀的黑匣子 archive 与 session 记录
+  - 不依赖模型在白天“自己记得写备忘”
+  - 产出 `journal/<date>.md` 与 `MEMORY.md` 的可审阅更新
+- 把 `archive-reader`、`memory-digest` 这类机制做成 skills 或等价装配点，而不是第二人格提示。
+
+### 10.5 验证与测试
+
+- 编写 scheduler 单元测试，覆盖下次触发时间、dedupe、busy 跳过。
+- 编写 routine 集成测试，覆盖手动运行、定时运行、push/writeback 行为。
+- 用一批样例 archive 文件执行 nightly digest，验证能稳定生成每日记忆与长期记忆。
+- 人工联调：
+  - 手动触发一条 routine
+  - 等待一条定时 routine
+  - 查看 run 记录
+  - 查看记忆文件输出
+
+### 10.6 DoD
+
+- 产品具备主动例行能力，而不只是被动聊天入口。
+- 原材料、run 记录、每日记忆、长期记忆已经形成可解释闭环。
+- 记忆生成依赖黑匣子原材料，而不是依赖模型白天临时自觉。
+- `routine list / run / enable / disable`、`push`、`append_markdown`、stale running 恢复均已有自动化回归。
+
+---
+
+## 11. Stage 8：Codex 直连远程文档能力（已完成）
+
+### 11.1 目标
+
+把 Feishu 文档能力收口为 **Codex 直接使用 Feishu Remote MCP**，避免在 `work-ally` 内再造一套文档 provider 子系统。
+
+### 11.2 范围
+
+本阶段只做四件事：
+
+- 为当前系统用户提供薄的 MCP 安装、检查、移除封装
+- 把“已有文档链接默认只读，除非用户明确要求修改”写成稳定产品规则
+- 把 Codex 针对 Feishu MCP 工具调用弹出的那类确认提示，收口为默认自动处理的实现策略
+- 从实现与文档中删除已废弃的旧文档发布路线
+
+### 11.3 依赖
+
+- Stage 7 完成
+
+### 11.4 实施任务
+
+- 新增并稳定 `ally mcp` 命令面：
+  - `status`
+  - `install-feishu`
+  - `remove-feishu`
+  - `list`
+- 约定 assistant desk 的 `.system/config.env` 中只保留一个远程文档相关入口：
+  - `FEISHU_MCP_SERVER_URL`
+- `install-feishu` 的本质应明确为：
+  - 对当前系统用户执行 `codex mcp add feishu --url ...`
+  - 不在 bridge 内再包一层远程文档读写实现
+- 删除已不再采用的旧实现与测试资产：
+  - 旧文档发布子系统
+  - streamable MCP provider
+  - local-file provider
+  - 旧预检入口及相关脚本、测试、文档
+- 把文档使用规则写进模板与维护文档：
+  - 用户给出已有飞书文档链接时，默认按只读参考处理
+  - 只有当用户明确要求“更新这个文档”时，才应写回
+  - “具备写能力”不等于“默认允许写”
+- 把工具调用确认策略写成稳定行为：
+  - `WORK_ALLY_MCP_TOOL_APPROVAL_ALLOWLIST=feishu:*` 默认开启
+  - ally 只自动处理受信任 MCP（当前默认 Feishu）发起的工具确认与对应 elicitation
+  - Runtime 的命令 / 文件审批仍保留人工确认边界
+- 保持架构边界：
+  - IM bridge 继续只做聊天、控制命令、编排、记忆闭环
+  - Feishu 文档读写能力属于 Codex 工具层，不属于 bridge 第二套实现
+
+### 11.5 验证与测试
+
+- shell 回归覆盖：
+  - `tests/shell/mcp.sh`
+  - `tests/shell/security.sh`
+- 至少验证这些行为：
+  - 缺少 `FEISHU_MCP_SERVER_URL` 时失败关闭
+  - `ally mcp install-feishu` 能写入当前用户的 Codex MCP 配置
+  - `ally mcp status` 能读取当前配置
+  - `ally mcp remove-feishu` 能移除该配置
+  - 默认不会把 Feishu MCP 工具调用确认抛给最终 IM 用户
+  - 真实文档读链路与一次最小追加写入链路可独立自测
+- 文档同步验证：
+  - README、快速开始、排障、实施指南、灯塔文档中不再出现旧文档发布路线
+  - 工作空间模板中已写明“已有远程文档链接默认只读”
+
+### 11.6 DoD
+
+- `work-ally` 不再保留自建远程文档 provider 实现或入口。
+- Feishu 文档能力的产品路线已统一为：**Codex 直接使用 Feishu Remote MCP**。
+- `.system/config.env` 与 `ally mcp *` 已足以让维护者完成 MCP 安装与排障。
+- “已有文档链接默认只读，明确要求后才修改”的规则已经写入模板与文档。
+- Feishu MCP 工具确认与对应 elicitation 已默认由 ally 自动处理，不再成为最终用户噪音。
+
+---
+
+## 12. Stage 9：运维、安全与交付封装（已完成）
+
+### 12.1 目标
+
+让产品从“功能能跑”提升到“用户能长期放心使用、升级、恢复、排障”。
+
+### 12.2 范围
+
+本阶段补齐交付封装、更新路径、服务化、可观测性与安全硬化。
+
+### 12.3 依赖
+
+- Stage 8 完成
+
+### 12.4 实施任务
+
+- 完成 `update` 语义：
+  - 更新产品内部实现
+  - 不污染工作空间资产
+  - 出错时能回滚或至少明确止损
+- 补齐日志、状态与诊断输出：
+  - `logs`
+  - `status`
+  - 状态文件
+  - 健康检查
+- 补齐工作空间级生命周期语义：
+  - `bridge.pid` 仅作为句柄，不作为唯一事实来源
+  - `start` / `stop` / `status` 能按工作空间归属发现并清理孤儿 bridge
+  - 重复 bridge 不再导致 stop 漏停与持续噪音
+- 为个人电脑模式准备常驻方案：
+  - 手动 `start`
+  - 可选服务化接管（如 `launchd` / `systemd` 等）
+  - 但无论何种方式都必须与官方 Codex 使用同一系统用户上下文
+- 补齐安全基线：
+  - allowlist 默认关闭，填写后严格生效
+  - 关键配置缺失时失败关闭
+  - 群聊默认走显式触发，不接受普通噪音消息
+  - 默认不开放公网回调
+  - 默认限制远程文档工具范围
+  - 明确 kill switch：`ally stop`
+- 补齐重建与恢复手册：
+  - 删除实现缓存后恢复
+  - 更换机器后恢复
+  - 凭据轮换与重新授权
+- 补齐运维文档：
+  - 启动
+  - 停止
+  - 更新
+  - 排障
+  - 恢复
+
+### 12.5 验证与测试
+
+- 做一次“从零初始化 -> 启动 -> 更新 -> 重启 -> 停止”的运维 smoke test。
+- 做一次“删掉内部实现 -> 恢复”的重建测试。
+- 做一次“缺失关键配置 / 凭据过期 / 未授权用户”的负向测试。
+- 做一次“远程文档权限受限目录 / 缺失 target node”的安全边界测试。
+
+### 12.6 DoD
+
+- 用户侧的交付形态已经清晰、稳定、可重建。
+- 出错时有清晰排障入口，而不是只能靠猜。
+- 安全基线已经从设计要求落实到默认行为。
+- 真实 `codex app-server` 探针、codex routine shell 验收与前台服务模式均已纳入自动化回归。
+
+---
+
+## 13. Stage 10：发布验收与完工出门（已完成）
+
+### 13.1 收口结论
+
+第一阶段最终已经完成下面四件事：
+
+- 自动化回归通过，`npm test` 与 `npm run test:maintainer` 都可作为稳定基线
+- 真人验收通过，覆盖 Feishu IM 闭环、控制命令、审批、routine / scheduler、nightly digest，以及 Feishu Remote MCP 的只读 / 显式写回边界
+- 干净工作空间交接通过，使用者可仅凭 `docs/user-quickstart.md` 完成接入、启动、恢复
+- 交付文档收口完成：用户快速开始、运维、排障、开发协作、人工验收、灯塔、实施指南口径已经统一
+
+### 13.2 关键验证结论
+
+- 工作空间资产与产品运行态已经分离
+- 用户只做必要动作，不需要理解内部实现模块
+- 黑匣子日志可以独立支撑维护者复盘，不再默认依赖用户手工回贴整段聊天记录
+- Runtime 原生能力边界已经明确：上下文、审批、MCP、thread 生命周期继续坚持“官方能力优先，ally 只做薄路由”
+
+### 13.3 DoD
+
+- 方案文档、实施指南、实现仓库与用户交付形态已经闭环
+- 一个新的实施者或用户仅靠交付文档（尤其是 `docs/user-quickstart.md`）就能完成接入、运行、更新与恢复
+- 可以对你汇报：**第一阶段产品开发完成**
+
+---
+
+## 14. 阶段推进硬规则
+
+为了防止项目又回到“想做很多，但每一块都没有封口”的状态，最后再把推进规则写死：
+
+- 每个阶段必须先过本阶段 DoD，再进入下一阶段主线。
+- 每个阶段都必须同步更新文档、测试与夹具，不能只交代码。
+- 每个阶段都必须保持模块边界，不允许把临时逻辑塞进门面或单个巨型脚本。
+- 如果阶段中发现灯塔文档需要修订，先修灯塔，再继续代码推进。
+- 如果某阶段尚未通过，但确实要预研后续阶段，预研结果不能冒充“已完成”。
+
+这份实施指南不是附属材料，而是完整产品开发的执行主线。