work-ally 0.2.0-alpha.1

package/docs/planning/product-workbench.md

@@ -0,0 +1,283 @@
+# Product Workbench
+
+更新时间：2026-03-23
+维护人：Ally
+
+这不是对外介绍文档，也不是单个 feature spec。
+
+说明：这份文档目前保留为产品账本原材料与历史清算入口，但不再承担日常调度、派工和优先级面板职责。
+根目录 `DASHBOARD.md` 是当前唯一日常工作台；本文件后续只做事实回写、漂移清算与必要收口，不再继续长成新的厚重 workbench。
+
+这份文档是 `work-ally` 的产品负责人工位文档，用来持续维护三件事：
+
+1. 当前到底已经交付了什么
+2. 哪些 planning/spec 已经过时或与实现漂移
+3. 下一阶段应该先收哪几条主线
+
+## 1. 使用原则
+
+### 1.1 文档优先级
+
+当文档之间出现冲突时，当前按下面顺序判断：
+
+1. `README.md`
+2. `docs/implementation/work-ally-implementation-guide.md`
+3. 自动化测试与当前实现
+4. `docs/completed/*.md`
+5. `docs/planning/*.md`
+
+也就是说：
+
+- planning 文档默认代表“意图”或“待落地方案”
+- README 与 implementation guide 默认代表“当前 shipped model”
+- 如果 planning 文档写着“未开始”，但实现和验收已经存在，优先认定为 **文档漂移**，不是功能未做
+
+### 1.2 状态定义
+
+- `已落地`：用户路径、实现、测试或验收口径已经成立
+- `部分落地`：底层能力已有，但产品表面、合同或文档还没收口
+- `未开始`：核心用户路径和主实现都还没有
+- `文档漂移`：功能已明显落地，但 spec / planning 状态未同步
+
+### 1.3 产品负责人工作规则
+
+后续所有新输入，先分成四类：
+
+- `bug / 回归`：已承诺能力失效，优先修复
+- `文档漂移`：实现与 spec 不一致，先收口口径
+- `feature`：新增或显著扩展产品语义，需要独立 spec
+- `调研项`：暂时还不够明确，先查清楚再决定是否立 spec
+
+对工程派工前，至少要收清楚：
+
+- 背景与问题定义
+- 目标与非目标
+- 用户路径
+- 系统边界
+- 验收标准
+- 当前依赖与风险
+
+## 2. 当前产品基线
+
+截至 2026-03-13，`work-ally` 的真实主线不是“早期原型”，而是已经完成 v1 主闭环。
+
+当前稳定基线可以概括为：
+
+- 一个运行中的 `ally` 进程对应一个 assistant desk
+- assistant 身份、记忆、对话和运行态进入 desk，而不是项目目录
+- `ally` 是唯一用户入口，支持 setup / start / stop / restart / status / logs / update / routine / mcp / global
+- Feishu 私聊主闭环已跑通，群聊支持最小显式触发闭环
+- 官方 Codex runtime 已接入，thread / approval / user input / stop / recover 已成立
+- archive raw layer、conversation view layer、nightly memory digest 已存在
+- supervisor、health、status、global list、logs、delivery gate 等运维壳已成立
+
+这意味着下一阶段的重点，不是“把产品从 0 做到 1”，而是：
+
+- 收口 spec 与实现的真实边界
+- 从工程能力继续产品化
+- 给后续派工建立稳定 inventory
+
+## 3. Feature Inventory
+
+| 模块 | 当前状态 | 判断 | 依据 | 下一步 |
+| --- | --- | --- | --- | --- |
+| Assistant desk / profile / 独立 `CODEX_HOME` | 已落地 | 用户可 setup 命名 assistant，拥有独立 desk 与 `CODEX_HOME` | `README.md`、`docs/manual-acceptance.md`、`internal/modules/assistant/manage.sh`、`internal/modules/runtime/status.sh` | 把相关 planning 文档改成已落地口径 |
+| 项目绑定与作用域命令 | 已落地 | 已形成 project scope / machine scope 语义 | `README.md`、`internal/dispatch.sh`、`internal/modules/global/manage.sh` | 后续只补可视化或摘要能力 |
+| 生命周期与托管 | 已落地 | `start/stop/restart/status` + supervisor + autosave 已成立 | `docs/manual-acceptance.md`、`internal/modules/runtime/*.sh` | 以稳定性和诊断为主，不另起新 spec |
+| Feishu 私聊主闭环 | 已落地 | 真实收发、控制命令、审批、恢复都已纳入 shipped model | `README.md`、implementation guide Stage 4-6、相关 integration tests | 保持稳定，不扩写新概念 |
+| Feishu Markdown-rich 回复 | 已落地 | 普通回复不再默认退化为纯文本 | `docs/manual-acceptance.md`、`docs/completed/FEATURE-feishu-markdown-and-reply-support.md` | 保持在 completed 目录，不再当作待做专题 |
+| Feishu reply context | 已落地 | reply target 正文会带入 prompt 上下文 | `docs/manual-acceptance.md`、`bridge/src/receiver.ts` | 与上项一起归档为已完成专题 |
+| Feishu `merge_forward` 转发聊天提取 | 部分落地 | 已支持提取转发聊天中的文本与链接，图片/媒体忽略；并把“这是转发聊天”语义显式带入 prompt | `bridge/src/channels/feishu/normalize.ts`、`bridge/src/channels/feishu/adapter.ts`、`bridge/src/receiver.ts`、相关 unit / integration tests | 仍缺一次真人 Feishu 验收；在验收前不把它提升为完全已收口 |
+| Feishu 群聊最小显式触发 | 已落地 | 仅显式呼叫、控制命令或直接 reply assistant 时触发 | `README.md`、`docs/manual-acceptance.md`、`bridge/src/channels/feishu/normalize.ts` | 后续再讨论更强群聊策略 |
+| 群聊 sender identity | 已落地 | group prompt 已带 sender envelope | `docs/completed/SPEC-group-chat-sender-identity.md`、`bridge/src/receiver.ts` | 保持在 completed 目录，不再当作待做专题 |
+| 远程 `/status`、审批、停止、user input | 已落地 | 已是 shipped UX，不再是预研 | implementation guide Stage 6、`bridge/src/receiver.ts`、integration tests | 后续只做轻量排版优化 |
+| MCP 薄封装与 Feishu 直连路线 | 已落地 | `work-ally` 不再自建文档执行层，只保留薄封装 | implementation guide Stage 8、`internal/modules/mcp/manage.sh` | 后续围绕只读 / 显式写回策略迭代 |
+| thread 会话原材料层 | 已落地 | 按 `thread/read(includeTurns=true)` 同步到 `memory/archive/YYYY/MM/DD/<threadId>.ndjson` | `bridge/src/thread-sync.ts`、`bridge/src/config.ts`、tests | 保持与官方 thread 语义一致 |
+| 会话读取来源统一 | 已落地 | Feishu 与 CLI 会话统一改为 thread 读取来源，不再维护中间层事件视图 | `README.md`、`bridge/src/thread-sync.ts`、相关 spec/tests | 后续只演进 thread 同步策略 |
+| routine / scheduler / nightly memory digest | 已落地 | 工程能力与夜间提炼已成立 | implementation guide Stage 7、`bridge/src/scheduler.ts`、`bridge/src/server.ts` | 下一步是产品化“定时任务” |
+| nightly memory digest 结果可见性 | 已落地 | digest 完成后会主动回告本次提炼结果；无新增稳定记忆也会明确说明 | `README.md`、`bridge/src/server.ts`、`tests/integration/routines/memory-pipeline.test.mjs`、`docs/completed/SPEC-nightly-memory-digest-visibility.md` | 后续只补失败/无目标场景的产品口径 |
+| memory 文件集合（`SOUL/NOW/MEMORY/MISTAKES/journal`） | 已落地 | 文件集、目录边界、nightly 输出已成立 | `README.md`、`internal/modules/assistant/manage.sh` | 继续收口注入与纠错合同 |
+| memory system 产品合同 | 部分落地 | 已有 archive、digest、memory files，但加载/删除/纠错合同未完全产品化 | `docs/planning/FEATURE-memory-system.md`、`bridge/src/memory-digest.ts` | 作为下一阶段主线之一继续补 spec |
+| 受管线程连续性 / surface mobility | 已落地 | `ally new|continue|attach|threads --assistant <name>`、Feishu `/new` `/codex` `/threads` `/takeover [handle]`、首条自然语言自动 materialize、assistant 专属 `CODEX_HOME` attach 与显式 surface binding 已补齐，并已通过产品验收；真实 Codex runtime smoke 仍受当前环境网络限制 | `docs/planning/SPEC-managed-thread-entry-and-surface-mobility.md`、`docs/planning/SPEC-codex-same-machine-session-handoff.md`、`docs/implementation/SPEC-codex-same-machine-session-handoff-implementation.md`、相关 unit / integration / shell tests | 作为 shipped baseline 维护；后续只在同一产品面内补细节，不再把它表述成待开工 handoff 专题 |
+| 会话状态可见性 / presence | 部分落地 | 已有 ack、progress heartbeat、审批/补充信息提示，以及“完成但无正文”时的结束回落提示；但更完整的 idle / 完成语义仍未完全产品化 | `bridge/src/receiver.ts`、`bridge/src/translator.ts`、`docs/planning/SPEC-session-presence-and-state-visibility.md` | 继续围绕更完整的 idle / 完成语义收口 |
+| 会话降噪与忙时输入门控 | 已落地 | 正常路径已默认降噪：reaction ack 之外不再补“已收到，开始处理。”这类通用状态；普通自然语言 follow-up 默认优先沿 `turn/steer` 进入当前 active turn，不再由 bridge 自创 busy gate 抢先拦截；只有已对用户可见的审批 / 补充信息阻塞才会在桥层先拦下；`/stop` 仍保留显式控制权，`/new` 忙时会先要求用户显式停止当前轮；`工作中` 状态已收口为飞书里的“工作进展”弱提示卡 | `bridge/src/receiver.ts`、`bridge/src/translator.ts`、`bridge/src/channels/feishu/formatter.ts`、`tests/integration/session/*.test.mjs`、`tests/unit/channel/formatter.test.mjs`、`docs/completed/SPEC-conversation-noise-reduction-and-busy-input-gate.md`、`docs/planning/SPEC-bridge-app-server-protocol-alignment.md` | 该专题当前已按产品验收收口；后续如再调整，只做细节优化，不改主合同 |
+| 审批自治边界 / 自测默认授权 | 已落地 | 当前项目根与 assistant desk 根内的低风险本地验证、局部改动、shell 包裹的自测 / commit 已默认静默自动放行；高风险边界仍保持人工拍板，且卡片会解释为什么需要你来定 | `bridge/src/receiver.ts`、`bridge/src/translator.ts`、`tests/integration/session/approval-flow.test.mjs`、`tests/integration/session/mcp-tool-approval-flow.test.mjs`、`docs/completed/SPEC-approval-autonomy-and-safe-defaults.md` | 后续只再细化 allowlist inventory，不回到逐条打断用户的默认路径 |
+| 中间层异常透明化 | 已落地 | delivery unavailable、runtime recovery required、runtime infrastructure failure、旧 turn 抑制与后续补告知都已进入用户可见路径；上一轮终态结果若当时未稳定送达，后续 inbound 到来时也会优先自动补发；runtime transport 生命周期已对用户静默，bridge 前台也已进一步收口为“默认只转发事实，不解释内部 recovery / stale cleanup / artifact pending” | `bridge/src/receiver.ts`、`bridge/src/channel-delivery.ts`、`bridge/src/session-store.ts`、`tests/integration/session/*.test.mjs`、`docs/completed/SPEC-middleware-exception-visibility.md`、`docs/planning/SPEC-minimal-bridge-semantics-and-user-visible-surface.md` | 后续只补更细的异常分层，不再接受“消息已进桥但用户完全无感”的默认行为 |
+| 极简桥梁语义与前台可见面收口 | 已落地 | bridge 前台已进一步收回到“默认只转发事实，不解释内部状态”；recovery attempt、stale cleanup、artifact pending 等解释型提示已默认静默，用户侧只保留必须行动或必须知道的最小信号 | `docs/planning/SPEC-minimal-bridge-semantics-and-user-visible-surface.md`、`bridge/src/receiver.ts`、`bridge/src/translator.ts`、`README.md`、`docs/user-quickstart.md`、`docs/manual-acceptance.md` | 作为 shipped baseline 维护；后续如再调整，只做边界内细化，不重回厚状态机 |
+| 多工程状态感知 | 部分落地 | 已有 `ally global list/stop`，但还不是产品级总览 | `README.md`、`internal/modules/global/manage.sh` | 暂缓做重面板，先补摘要模型 |
+| 轻量桌面控制壳 / Desktop Control Plane | 已落地（Phase 2 shipped） | machine-wide backend、桌面 / 浏览器双态 renderer、Pixel Office 总览、项目三栏主路径、三层状态、控制闭环与核心长期资产编辑已完成实现与自测；Phase 2 的 wrapper 边界、overview/detail `Next Step`、create / bind / save inputs 连续导流、桌面 Quick Start 与公开入口口径也已收口 | `README.md`、`PRODUCT.md`、`desktop/backend/rust/`、`desktop/renderer/`、`desktop/src-tauri/`、`tests/desktop/`、`docs/implementation/desktop-control-plane-phase1-implementation.md`、`docs/planning/SPEC-desktop-phase2-onboarding-and-distribution.md`、`docs/implementation/desktop-phase2-onboarding-implementation.md` | 后续在已公开的包装层基线上继续迭代，不再把桌面控制面表述成“内测中” |
+| Active turn 默认 steer / context compaction 可见性 | 已落地 | 默认 follow-up 直接走 `turn/steer`；bridge 在观测到 `contextCompaction` / `thread/compacted` 时会向前台发送一次轻量系统提示，不引入 queue 模式或额外配置 | `docs/planning/SPEC-active-turn-steer-and-context-compaction-visibility.md`、`bridge/src/runtime-client.ts`、`bridge/src/receiver.ts`、`tests/integration/session/protocol-routing.test.mjs` | 后续只继续观察真实渠道里的提示频率是否还需要进一步收噪 |
+| Feishu reaction shortcuts 作为输入 | 未开始 | 当前只有 ack reaction，没有把用户 reaction 作为语义输入 | `docs/planning/SPEC-feishu-reaction-shortcuts.md`、`bridge/src/channels/feishu/adapter.ts` | 可做小 feature，但不是当前主线 |
+| 聊天内自然注册“定时任务” | 未开始 | 现有是 routine/scheduler 工程能力，不是用户自然语言注册 | `docs/planning/ally-next.md`、`bridge/src/server.ts` | 这是下一阶段最高优先级 feature |
+| mode / reasoning depth | 未开始 | 只有 profile 默认值，没有用户可感知的 mode 层 | `docs/planning/ally-next.md`、`internal/modules/assistant/manage.sh` | 放在定时任务/记忆/会话之后 |
+| reviewer / 交叉评审 | 未开始 | 还没有 reviewer mode 或 detached review lane | `docs/planning/ally-next.md` | 作为第二层增强 |
+| 汇报与把关 | 未开始 | 有种子能力，但没有独立产品 feature | `docs/planning/ally-next.md` | 建立在 mode/reviewer/定时任务稳定之后 |
+| 多 Agent 协同 | 未开始 | 当前明确不进入主线 | `docs/planning/ally-next.md` | 继续停留在预研 |
+
+## 4. 文档漂移清单
+
+以下不是“功能没做”，而是“文档状态已经落后于实现”。
+
+### 4.1 `assistant-workbench-spec.md`
+
+当前问题：
+
+- 文档写的是 `Draft / Ready for implementation`
+- 任务拆分里大量条目写着“未开始”
+- 但 assistant 注册、独立 desk、独立 `CODEX_HOME`、状态可见性、配置独立策略都已经明显存在
+
+当前判断：
+
+- 这份文档不能再被当作“未开始 feature spec”使用
+- 应改写为“已落地路线回写”或拆成“已完成设计 + 后续增量”
+
+### 4.2 `SPEC-stable-archive-contract.md`
+
+当前问题：
+
+- 文档状态仍写 `proposed for review before implementation pass`
+- 但 archive 的主目录结构和事件落盘已经在实现里存在
+
+当前判断：
+
+- 主体合同已经进入 shipped 范围
+- 需要补一轮“实现 vs 合同”核对后，把文档状态切到已落地或已冻结
+
+### 4.3 `FEATURE-memory-system.md`
+
+当前问题：
+
+- 文档仍偏“准备评审前 spec”口吻
+- 实际上 memory 文件集、nightly digest、archive/conversations 分层都已经存在
+
+当前判断：
+
+- 这份文档不应再描述成从零设计
+- 应拆成“已落地基线”与“未收口合同”两部分
+
+### 4.4 `SPEC-lightweight-desktop-control-panel.md`
+
+当前问题：
+
+- 文档状态仍是 `Ready for implementation`
+- 但 README、PRODUCT、desktop 实现目录与 `tests/desktop/` 已证明 Phase 1 已经落地并完成自动化验证
+- 文档正文仍以“准备开工”口吻为主，容易误导后续把已做完的 Phase 1 当成待实现 feature
+
+当前判断：
+
+- 这份文档应更新为 `Partially shipped / Phase 1 landed`
+- 文档需要明确：当前待推进的是 Phase 2 / Phase 3，而不是整条桌面控制面 feature 尚未开始
+
+### 4.5 `SPEC-middleware-exception-visibility.md`
+
+当前问题：
+
+- 文档已进入 `docs/completed/`
+- 但头部状态仍写 `planning`
+
+当前判断：
+
+- 状态必须改成 shipped baseline，避免 completed 目录与文档头部互相打架
+
+### 4.6 `NOW.md`
+
+当前问题：
+
+- 便签仍停留在“审批自治边界 / 中间层异常透明化正在推进”的旧状态
+- 与 README、product workbench 和最近提交已经不一致
+
+当前判断：
+
+- 应回填为“文档清算 + 桌面控制面 / 受管线程连续性口径收口”的当前工作态
+
+### 4.7 受管线程连续性状态回写
+
+当前问题：
+
+- 受管线程连续性基线已经通过产品验收，但若产品账本与入口文档仍保留“进行验收 / 待开工”口吻，会继续制造状态错觉。
+
+当前判断：
+
+- 受管线程连续性主线应整体按“已落地、主合同成立”维护。
+- 真实 Codex runtime smoke 的环境缺口要如实保留，但不再因此把专题挂在“待验收”栏。
+
+## 5. 当前优先级顺序
+
+这里只做一件事：给出当前 spec 的**扁平优先级排序**。
+
+这份排序：
+
+- 不绑定时间
+- 不预估人天
+- 不假设固定团队规模
+- 只表达“先做什么，后做什么”
+
+同时要先区分两类文档：
+
+### 5.1 作为直接派工输入的 spec
+
+这些 spec 应被理解为可以直接进入实现排序的工作项。
+
+当前推荐顺序如下：
+
+先说明：上一个阶段排在最前的三条体验专项已经完成交付，不再作为“待派工前排项”重复排队：
+
+- `会话降噪与忙时输入门控`
+- `审批自治边界 / 自测默认授权`
+- `中间层异常透明化`
+
+桌面控制面 Phase 1 已经落地，因此不再列入“待实现 feature”排序；当前从仍需继续推进的专题开始排序：
+
+1. **会话恢复与状态合同收口**
+   - 主输入：`docs/planning/SPEC-runtime-connection-and-turn-recovery-semantics.md`
+   - 这是对会话异常、恢复、重发语义的进一步收口，应排在上面几条体验主线之后
+2. **定时任务产品化**
+   - 当前主输入仍在 `docs/planning/ally-next.md`
+   - 已有地基，但还缺正式独立 spec；在进入实现前应先补成项目级 spec
+3. **memory system 收口**
+   - 主输入：`docs/planning/FEATURE-memory-system.md`
+   - 应先拆清“已落地基线”和“待收口合同”，再进入更靠前位置
+4. **runtime abstraction phase 1**
+   - 主输入：`docs/planning/SPEC-runtime-abstraction-phase-1.md`
+   - 这是明确的重构型专题，重要但应后置于当前体验修补项之后
+5. **Claude runtime host**
+   - 主输入：`docs/planning/SPEC-claude-runtime-host-for-work-ally.md`
+   - 这是可选扩展项，依赖更高，也应排在现阶段真实体验问题之后
+
+### 5.2 作为总纲 / 背景合同的 spec
+
+这些 spec 很重要，但不应被误当作与上面并排抢顺位的直接实现项。
+
+1. `docs/planning/SPEC-user-barrier-reduction-and-activation.md`
+   - 这是“降低用户门槛”主专项的总 spec
+   - 它负责统一入口承接、首次激活、状态理解、失败恢复这些大方向
+   - 不作为单独实现项排队，而作为桌面控制壳、准入闭环、状态理解等专题的上位约束
+2. `docs/planning/SPEC-session-presence-and-state-visibility.md`
+   - 这是会话状态可见性的基础合同
+   - 但它当前已被“会话降噪与忙时输入门控”“异常透明化”“恢复语义”几条专题部分吸收
+   - 不建议再把它当成一个独立前排 feature 推进，而应视为背景合同并逐步回写收口
+
+### 5.3 当前排序原则
+
+当前排序不是按“架构重要性”排，而是按下面四条综合判断：
+
+1. 是否直接命中真实使用中的高频痛点
+2. 是否能明显改善用户体感与产品可信度
+3. 是否属于相对独立、容易被单独消化的专题
+4. 是否是重构型、扩展型、可后置型工作
+
+当前明确判断：
+
+> 先消化真实使用中已经暴露出来的小而关键的体验问题，再处理重构型与未来扩展型专题。
+
+## 6. 维护动作
+
+后续由产品负责人持续维护这份文档，至少遵守下面三条：
+
+1. 每次功能真正 shipped 后，先更新 inventory，再谈下一条 spec
+2. 每次发现 planning 文档与实现冲突，优先登记为“文档漂移”而不是口头记住
+3. 每次准备派工前，先从这里确认该 feature 是补缺口、扩能力，还是只是修正文档
+
+当前结论：
+
+> `work-ally` 的下一个阶段，不是盲目加 feature，而是先把产品负责人的事实账本收稳，再围绕“降低用户门槛”、定时任务、会话恢复语义、memory system 几条主线推进。

package/docs/product-onboarding.md

@@ -0,0 +1,227 @@
+# 产品同事入场指引
+
+这份文档服务于新加入 `work-ally` 的产品同事。
+
+目标不是重复定义产品是什么，而是帮助你快速建立三件事：
+
+1. 产品总纲应该先看哪里
+2. 当前已经做到哪里
+3. 接下来该按什么顺序读文档
+
+## 先看什么
+
+如果你第一次接触这个产品，先按这个顺序：
+
+1. `PRODUCT.md`
+2. `README.md`
+3. `docs/architecture/codex-feishu-bridge-proposal.md`
+4. `docs/implementation/work-ally-implementation-guide.md`
+
+其中：
+
+- `PRODUCT.md` 负责回答“这个产品是什么、为什么存在、边界是什么”
+- `README.md` 负责回答“当前 shipped model 是什么、仓库结构是什么、维护入口在哪里”
+
+如果看到历史文档里有更早期的表达，例如“项目目录内 `.work-ally/` 承载长期资产”等，请优先以 `PRODUCT.md`、当前 `README.md` 和相关文档开头写明的 shipped model 为准。
+
+再补一条文档判断纪律：
+
+- 门面性文档只看当前 shipped model，不看演进过程
+- 过程性文档可以看 feature、专题、阶段和历史取舍，但不要把里面的旧现状描述误读成当前系统行为
+
+## 你应该先看什么
+
+推荐顺序：
+
+1. `PRODUCT.md`
+2. `README.md`
+3. `DASHBOARD.md`
+4. `docs/architecture/codex-feishu-bridge-proposal.md`
+5. `docs/implementation/work-ally-implementation-guide.md`
+6. `docs/completed/`
+7. `docs/planning/`
+8. `docs/user-quickstart.md`
+9. 最后回看 `docs/manual-acceptance.md`，按验收口径核对主线能力
+
+每份文档的职责如下。
+
+## 文档地图
+
+### 1. `PRODUCT.md`
+
+这是产品介绍总入口。
+
+你应该先从这里建立：
+
+- 这个产品是什么
+- 为什么要做
+- 产品架构是什么
+- 有什么功能
+- 不打算做什么
+
+如果你要向老板、同事或新伙伴介绍 `work-ally`，优先直接给这份文档。
+
+### 2. `README.md`
+
+这是整个仓库的工程总览入口。
+
+你应该从这里建立：
+
+- 当前 shipped model
+- 仓库结构
+- 运行边界
+- 当前维护与查看入口
+
+如果你已经知道产品是什么，但还不知道工程上现在做到哪里，就看它。
+
+### 3. `DASHBOARD.md`
+
+这是产品负责人 / 项目负责人的轻量驾驶舱。
+
+你应该从这里快速建立：
+
+- 当前有哪些主线正在推进
+- 哪些事项已经 ready，可派工认领
+- 哪些只是想法，还没进到可开发状态
+- 哪些高价值能力已经完成，不需要重复讨论
+
+它不是长期灯塔，也不是工程实现细节文档；它的作用是帮助你快速回到“现在该做什么”。
+
+在当前产品协作里，可以把它粗略理解成一个轻量看板：
+
+- `进行中`：已经在施工
+- `待开发`：边界已清楚，可派工认领
+- `待验收`：实现已基本到位，但还缺产品确认或真人链路验收
+- `规划中` / `想法池`：还不能直接开工
+
+注意：这里的“做到哪里”指当前可交付现状，不是实现演进史。
+
+### 4. `docs/architecture/`
+
+这里是灯塔文档层，主要回答：
+
+- 为什么产品边界要这样划
+- 为什么不再造第二套 agent 脑子
+- 为什么 assistant desk 和项目目录要分离
+- 为什么 Feishu 只是远程触达媒介，而不是智能本体
+
+当前最重要的是：
+
+- `docs/architecture/codex-feishu-bridge-proposal.md`
+
+### 5. `docs/implementation/`
+
+这里回答的是：
+
+- 这条产品线是怎么分阶段做下来的
+- 当前实现已经覆盖到哪里
+- 哪些阶段已经完成
+- 当前交付口径是什么
+
+当前最重要的是：
+
+- `docs/implementation/work-ally-implementation-guide.md`
+
+如果你想知道“现在不是在讨论概念，而是真正做到什么程度了”，优先看这里。
+
+但要注意：`docs/implementation/` 属于过程性文档，允许保留阶段、DOD、专题收口与实现演进；阅读时要优先以文档顶部的 shipped model 和当前结论为准，不要把历史阶段中的早期设计误当成现状。
+
+### 6. `docs/completed/`
+
+这里是已完成专题层，适合看：
+
+- 哪些专题已经真正落地
+- 哪些 spec 不该再被当作待做项
+- 哪些能力已经进入 shipped 范围
+
+比较关键的包括：
+
+- `docs/completed/FEATURE-feishu-markdown-and-reply-support.md`
+- `docs/completed/SPEC-group-chat-sender-identity.md`
+
+### 7. `docs/planning/`
+
+这里是规划层，适合看：
+
+- 下一阶段 feature spec
+- 专题设计稿
+- 中长期方向
+
+可以把它理解为“未来工作篮子”。
+
+比较关键的包括：
+
+- `docs/planning/ally-next.md`
+- `docs/planning/product-workbench.md`
+- `docs/planning/SPEC-codex-same-machine-session-handoff.md`
+- `docs/planning/FEATURE-memory-system.md`
+- `docs/planning/SPEC-stable-archive-contract.md`
+
+注意：
+
+- `docs/planning/assistant-workbench-spec.md` 已明显带有历史漂移，不应再当作当前主线 feature spec 使用
+- same-machine handoff 现在看 `docs/planning/SPEC-codex-same-machine-session-handoff.md` 与对应 implementation spec / `TASK.md`
+- 这条线已经通过产品验收；planning spec 在这里承担的是产品合同与边界文档，不再表示“待开工”
+
+### 8. `docs/user-quickstart.md`
+
+这是当前正式 CLI 用户视角的主路径。
+
+产品同事看它的意义不是学命令，而是反看：
+
+- 当前我们对用户暴露了什么
+- 用户默认路径有多长
+- 哪些概念被隐藏在中间层里
+- 当前体验是否符合“默认简单、内部消化复杂性”的原则
+
+### 9. `docs/developer-workflow.md` / `docs/ops-runbook.md` / `docs/troubleshooting.md`
+
+这三份更多是研发、联调、运维、排障手册。
+
+产品同事不需要一开始就逐行细看，但在下面场景会用到：
+
+- 你要确认某个 feature 的验证方式
+- 你要理解某个线上问题的排查路径
+- 你要跟工程一起判断某个问题是实现缺陷、运维故障，还是产品边界问题
+
+### 10. `docs/manual-acceptance.md`
+
+这是人工验收清单。
+
+适合用来回答：
+
+- 当前版本到底承诺了哪些事
+- 哪些体验已经被当作交付基线
+- 提需求时怎样写出更接近验收口径的目标
+
+## 当前建议的理解框架
+
+看这个产品时，建议始终按四层理解：
+
+1. 项目工作现场
+2. assistant desk
+3. `work-ally` 中间层
+4. 官方 Codex runtime
+
+很多讨论如果混乱，通常是把这四层的职责揉在了一起。
+
+## 作为产品同事，你最值得先抓住的几个判断
+
+- 产品应该尽量把复杂性吃在中间层，而不是甩给用户。
+- 用户不应该被迫理解端口、内部运行态、桥接细节等工程概念。
+- assistant desk 属于 assistant 自己；项目级知识、规则、设计与规划属于项目仓库。
+- 文档应优先项目级沉淀，避免依赖某个 assistant 私有 desk 才能理解产品。
+- 讨论方案时，先区分用户问题、系统根因和产品边界，再谈实现方案。
+
+## 入场后建议的第一轮动作
+
+1. 先通读 `PRODUCT.md`
+2. 再看 `README.md`
+3. 再看架构灯塔文档
+4. 再确认实施主线和当前完成面
+5. 先扫一遍 `docs/completed/`，确认哪些专题已经不该重复讨论
+6. 然后按你关心的专题去看 `docs/planning/`
+7. 最后回看 `docs/user-quickstart.md` 和 `docs/manual-acceptance.md`，从当前正式用户路径和验收口径校准判断
+8. 对照 `DASHBOARD.md` 与 planning spec，确认下一阶段派工优先级
+
+这样可以先建立产品判断，再进入需求细节，而不是一上来陷进实现碎片里。