work-ally 0.2.0-alpha.1

package/docs/planning/SPEC-claude-runtime-host-for-work-ally.md

@@ -0,0 +1,434 @@
+# Claude Runtime Host For work-ally
+
+## Status
+
+- Target project: `work-ally`
+- Audience: product owner / implementation engineer
+- Scope: Claude Runtime Host, Claude Agent SDK mapping, minimal app-server-like contract for `work-ally`
+- Status: planning
+- Goal: package Claude Agent SDK behind a minimal runtime host that matches the `work-ally` runtime contract closely enough for optional future integration
+
+## Summary
+
+这份 spec 是 **Phase 2 / 可选扩展 spec**。
+
+它不负责重构 `work-ally` 主线，也不负责立刻把 Claude 接进生产路径。
+
+它要做的事情只有一件：
+
+> 基于 Claude Agent SDK，包装出一个面向 `work-ally` 的最小 Runtime Host，让上层未来可以像接入另一个 runtime impl 一样去接它。
+
+这里有两个边界必须先讲清楚：
+
+1. 它不是一个野心很大的“Claude App Server 通用平台”
+2. 它也不是把 `claude` CLI 随便包一层壳
+
+它应是一个**只服务于 `work-ally runtime contract` 的最小 host / shim**。
+
+因此，这条 spec 可以并行推进，也可以最后被砍掉：
+
+- 如果做成了，`work-ally` 获得第二 runtime 选择
+- 如果做不成，`work-ally` 仍然保持 Codex 主线稳定，不受影响
+
+## Relationship To Phase 1
+
+### 1. 逻辑关系
+
+产品顺序上：
+
+- Phase 1 先定义并收稳 runtime abstraction
+- Phase 2 再把 Claude 包装成符合该抽象的实现
+
+### 2. 执行关系
+
+工程推进上，Phase 2 可以部分并行：
+
+- 可以先研究 Claude Agent SDK
+- 可以先做独立 host prototype
+- 可以先验证 SDK 到 host contract 的映射
+
+但最终要不要接入 `work-ally` 主线，仍然取决于：
+
+- Phase 1 contract 是否稳定
+- Claude host 是否满足最小接入条件
+
+### 3. 风险关系
+
+必须保证：
+
+> Phase 2 失败，不得反伤 Phase 1，更不得损伤当前 Codex 用户。
+
+## Background
+
+支持 Claude 的动机，不应是“技术上很酷”，而应是清晰的产品理由：
+
+- 降低组织内推广时的 runtime 偏好阻力
+- 减少“先接受 Codex 才能接受 work-ally”的前置门槛
+- 为未来开源留出更大的适用面
+
+但是否真的值得做 Claude，也必须持续反问：
+
+> 同样能做事情，为什么一定要接 Claude？
+
+因此，这条 spec 从一开始就要自带 go / no-go 意识。
+
+另一方面，基于对 `nanoclaw` 的研究，可以确认三件事：
+
+1. Claude Agent SDK 足以承接会话、调度、隔离执行这些上层能力
+2. Claude 侧更像 `session + async iterator + hooks + permission callbacks`
+3. 它并不是 Codex App Server 的同构替代物
+
+这意味着正确方向不是“直接把 Claude SDK 塞进 bridge”，而是先包一层 host。
+
+## Problem Statement
+
+Phase 2 要解决三个问题。
+
+### 1. Claude Agent SDK 与 `work-ally` 当前消费层级不一致
+
+`work-ally` 当前更接近消费一个 runtime host / app-server 式能力面。
+
+而 Claude Agent SDK 暴露的是：
+
+- session / resume
+- async iterator message stream
+- interrupt
+- permission callbacks
+- hooks
+- settingSources
+- MCP server wiring
+
+如果直接把这些原始语义灌进 `work-ally` bridge，会让上层抽象变脏。
+
+### 2. Claude 的 gate model 不等于 Codex 的 approval model
+
+Codex 当前可以较自然地产生 approval / user-input 事件。
+
+Claude 更可能通过：
+
+- `canUseTool`
+- permissionMode
+- hooks
+- session control
+
+来间接表达“这里需要人类决策”。
+
+如果不单独包 host，这种差异会直接污染产品主链路。
+
+### 3. 需要在接入前判断是否值得做
+
+不是所有“能接”的东西都值得接。
+
+Claude host 必须先证明：
+
+- 它能满足最小 contract
+- 它的维护成本可接受
+- 它不会迫使 `work-ally` 为它改坏现有 Codex 体验
+
+## Product Decision
+
+### Decision 1: Phase 2 是可选扩展，不是主线前提
+
+Claude Runtime Host 不是当前产品成立的前提。
+
+它的地位应明确为：
+
+- 可选扩展
+- 价值验证项
+- 做成再接，做不成就不接
+
+### Decision 2: Host 只做最小封装，不做通用平台
+
+Host 的目标不是复刻一个完整的“Claude App Server”。
+
+它只需要满足 `work-ally` 真正需要的最小 contract。
+
+这意味着：
+
+- 不做额外控制台
+- 不做多租户平台
+- 不做广义的 provider layer
+- 不做超过 `work-ally` 需求的通用 server 野心
+
+### Decision 3: 先追求产品语义对齐，不追求协议长相一致
+
+我们追求的是：
+
+- `work-ally` 上层看到的产品语义一致
+
+而不是：
+
+- Claude host 在底层长得和 Codex App Server 一模一样
+
+因此允许：
+
+- 底层实现不同
+- 原生事件形状不同
+- 只要 adapter / host 能提供同样的产品合同即可
+
+### Decision 4: Claude host 的核心难点是 gate semantics，不是 run turn
+
+跑一轮 prompt、拿一个结果，这不是最难的部分。
+
+真正难的是：
+
+- 什么时候停下来找人
+- 人如何回复
+- 回复后如何继续
+- 这些行为如何稳定映射到 Feishu 远程协作语义
+
+所以 Phase 2 的验收重点必须放在 gate semantics，而不是只放在“跑通一次会话”。
+
+## Goals
+
+1. 基于 Claude Agent SDK 定义一个最小 Runtime Host
+2. 让该 Host 能映射到 `work-ally` runtime contract
+3. 验证 Claude 路线在 `work-ally` 里是否具备现实接入价值
+4. 为后续正式接入提供清晰的 go / no-go 判断依据
+
+## Non-goals
+
+Phase 2 不做：
+
+- 承诺一定把 Claude 接进生产主线
+- 复刻完整 Codex App Server 协议
+- 提供一个通用外部开放平台供无关项目直接复用
+- 在第一版就支持所有 Claude 能力或全部 SDK 特性
+- 为了兼容 Claude 改坏 `work-ally` 主线抽象
+
+## Scope
+
+### In scope
+
+1. 研究 Claude Agent SDK 的正式能力面
+2. 定义一个最小 Claude Runtime Host contract
+3. 明确 SDK 到 host contract 的映射
+4. 明确 host 到 `work-ally` runtime contract 的映射
+5. 做最小 host prototype / spike
+6. 形成 capability matrix、降级语义和 go / no-go 结论
+
+### Out of scope
+
+1. 直接修改 `work-ally` 主线接入 Claude
+2. 承诺对外正式支持 Claude
+3. 设计多 runtime UI 或切换面板
+
+## Minimal Host Contract
+
+Claude Runtime Host 至少应提供下面这些能力面。
+
+### 1. Required host surface
+
+1. `healthcheck`
+2. `start_session`
+3. `resume_session`
+4. `run_turn`
+5. `interrupt_turn`
+6. `read_session_status`
+7. `disconnect`
+
+### 2. Desired host surface
+
+1. progress stream
+2. gate semantics
+3. turn result recovery or bounded confirmation support
+4. session metadata
+5. capability declaration
+
+### 3. Explicitly allowed mismatch
+
+下面这些地方不要求与 Codex 完全同构：
+
+- 原生 event 名称
+- 原生 message shape
+- session 内部实现方式
+- permission / gate 的底层来源
+
+真正要求一致的是：
+
+- host 对外提供给 `work-ally` 的 contract
+
+## Mapping: Claude SDK -> Host
+
+这部分是第二个工程师最需要的一节。
+
+### 1. Session lifecycle mapping
+
+Claude SDK 侧重点能力：
+
+- `query()`
+- `resume`
+- session object / persistent session 能力
+- `interrupt()`
+
+Host 要负责把这些能力映射成：
+
+- start session
+- resume session
+- run turn
+- interrupt current turn
+
+### 2. Progress mapping
+
+Claude SDK 可能提供的相关信号包括：
+
+- partial messages
+- tool progress
+- task notifications
+- hook progress
+
+Host 需要判断：
+
+- 哪些可以转成 `work-ally` 的 progress events
+- 哪些只能内部使用
+- 哪些只能被合成为较粗粒度状态
+
+### 3. Gate mapping
+
+这是最关键映射。
+
+Host 需要把下面这些 Claude-side 能力，整理成 `work-ally` 能消费的 gate semantics：
+
+- `canUseTool`
+- permission mode
+- hooks
+- 需要用户继续输入或确认的场景
+
+关键不是保留原始形状，而是产出统一合同：
+
+- 触发什么 gate
+- 发给用户什么信息
+- 收到用户回复后怎么继续
+
+### 4. Context / instruction loading mapping
+
+Claude SDK 有自己的 `settingSources`、`systemPrompt`、additional directories 等能力。
+
+Host 需要明确：
+
+- 如何承接项目级规则
+- 如何承接 assistant desk 规则
+- 是否支持 desk / project 双边界注入
+- 何处是 host 自己的内部配置，何处由 `work-ally` 提供
+
+### 5. MCP mapping
+
+Host 需要明确：
+
+- Claude SDK 下 MCP server 如何挂接
+- 与 `work-ally` 当前的 MCP 使用边界是否冲突
+- 哪些 MCP 行为属于 host 内部，哪些属于上层 contract
+
+## Implementation Direction
+
+### Step 1: Capability inventory
+
+先做一份明确的 Claude SDK capability inventory：
+
+- 会话能力
+- 中断能力
+- partial / progress 能力
+- permission / hook 能力
+- MCP 能力
+- context / settingSources 能力
+
+### Step 2: Host contract draft
+
+基于 inventory 定义最小 host contract，而不是直接开写实现。
+
+### Step 3: Prototype
+
+做一个最小 host prototype，只验证：
+
+- start
+- resume
+- run turn
+- interrupt
+- 最小 progress
+- 最小 gate semantics
+
+### Step 4: Gap analysis
+
+输出 capability matrix：
+
+- 已满足
+- 可降级满足
+- 当前缺失
+- 必须阻塞正式接入
+
+### Step 5: Integration recommendation
+
+最后才给出结论：
+
+- 值得进入 `work-ally`
+- 暂缓
+- 放弃
+
+## Go / No-Go Criteria
+
+满足以下条件，Claude Host 才值得进入下一步接入评审：
+
+1. 能稳定新建和恢复会话
+2. 能稳定跑完最小 turn
+3. 能中断
+4. 能给出至少可接受的 progress / working 语义
+5. 能稳定表达 gate semantics
+6. 不要求 `work-ally` 为它改坏当前 Codex 抽象
+7. 维护成本可接受
+
+任一关键项不满足，都可以判定：
+
+- 暂不接入 `work-ally`
+
+## Deliverables
+
+Phase 2 完成时，至少应交付：
+
+1. 一份 Claude SDK capability inventory
+2. 一份最小 Claude Runtime Host contract
+3. 一个 host prototype 或 spike 实现
+4. 一份 capability matrix
+5. 一份明确的 go / no-go 结论
+
+## Acceptance Criteria
+
+1. 第二个工程师只看这份 spec，就能理解 host 的目标、边界和成功标准
+2. spec 已明确写清：它是最小 host，不是通用平台
+3. spec 已明确写清：它可以并行推进，也可以最终被砍掉
+4. host 的关键难点和验收重心已放在 gate semantics，而不是只看单轮 prompt
+5. 输出物里包含 capability matrix 和接入建议，而不是只有 demo
+
+## Risks
+
+### 1. 误把 host 做成通用平台
+
+会迅速膨胀，也会偏离 `work-ally` 的真实需求。
+
+### 2. 误把 Claude permission model 当成 Codex approval model
+
+会导致抽象别扭、实现脆弱，最后逼着 `work-ally` 主链路到处打补丁。
+
+### 3. 只看“能跑起来”，忽视远程协作语义
+
+如果 host 只会本地跑 prompt，但无法提供稳定 gate semantics，就不适合接进 `work-ally`。
+
+### 4. 维护成本高于用户价值
+
+即使技术上能做，也不代表产品上值得做。
+
+## Open Questions
+
+1. Claude SDK 的哪条 session API 最适合作为 host 的稳定基础
+2. desk / project 双边界注入的最佳承接方式是什么
+3. gate semantics 应该在 host 内完成多少，留给 adapter 层多少
+4. 如果 progress 只能粗粒度合成，是否仍足以满足 `work-ally` 的远程协作要求
+
+## Product Judgment
+
+Phase 2 的正确定位不是“我们一定要支持 Claude”。
+
+而是：
+
+> 我们给自己一个低风险、可验证、可放弃的机会，去判断 Claude 路线是否真的值得成为 `work-ally` 的第二 runtime。
+
+如果答案是 yes，就接；如果答案是 no，就停。无论结果如何，都不应伤到当前 Codex 主线。

package/docs/planning/SPEC-cli-feishu-codex-session-unification.md

@@ -0,0 +1,236 @@
+# SPEC: CLI-Only + Feishu/Codex 会话互通主线重构（Thread Read Pull 模式）
+
+更新时间：2026-03-31  
+状态：In Progress  
+Owner：work-ally
+相关文档：
+- `AGENTS.md`
+- `README.md`
+- `docs/product-spec-standard.md`
+- `docs/planning/SPEC-codex-same-machine-session-handoff.md`
+- `docs/planning/SPEC-managed-thread-entry-and-surface-mobility.md`
+
+## 1. Summary
+
+本次变更将 `work-ally` 从“CLI + Desktop 并行入口”收敛为单一主线，并把会话材料采集方式明确为 **Thread Read Pull**：
+
+1. 唯一产品入口是 CLI（`./ally.sh <command>`）。
+2. 产品核心价值是让用户可在 Feishu 与官方 `codex` CLI 间无缝切换并连续使用同一会话。
+3. 会话留痕不再由中间层按消息事件增量记录，也不使用 Hook 方案；统一改为按时机对 thread 执行 `thread/read(includeTurns=true)` 拉取并覆盖写本地材料。
+4. 记忆系统以 thread 拉取得到的“用户/assistant 对话正文”作为原材料，统一沉淀到 assistant desk。
+
+其中 `ally codex` 的定位是：
+
+1. 它是官方 `codex` 命令的受管启动入口（wrapper / launcher）。
+2. `work-ally` 在启动前注入 assistant 绑定的 profile 上下文（至少含 `CODEX_HOME` 与相关会话互通所需环境）。
+3. 真正执行会话的仍是官方 `codex`，不是中间层自实现 runtime。
+
+一句话定义：
+
+> `work-ally` 是官方 Codex CLI 的会话互通层与渠道编排层，不是独立会话系统。
+
+## 2. 背景
+
+当前仓库存在两条并行叙事：
+
+1. Desktop Control Plane 作为正式包装入口。
+2. Feishu 与 CLI 的互通与接续能力持续增强。
+
+方向变更后，产品目标更明确：
+
+1. 不再支持桌面端。
+2. 主打“Feishu 可用 + 官方 Codex CLI 可用 + 同一会话连续”。
+3. 若用户临时离开 Feishu 转到官方 `codex`，会话仍可回溯与续接。
+
+同时，增量监听式会话落库在工程上会形成第二事实源；因此本次改为 thread 全量读取并覆盖写，保证“来源单一、结构稳定、实现可审计”。
+
+## 3. 问题定义
+
+### 3.1 入口与产品语义分散
+
+Desktop 与 CLI 并行导致用户对“主入口”认知不一致，维护口径与文档口径被分散。
+
+### 3.2 会话真相源重复
+
+当中间层保存一套聊天记录、官方 Codex 再保存一套会话轨迹时，会出现：
+
+1. 事实源不唯一。
+2. 跨 Feishu 与官方 CLI 的会话连续性依赖额外映射。
+3. 用户离开 Feishu 后会话留存不稳定。
+
+### 3.3 profile 不统一导致无法无缝续接
+
+若不是由 `work-ally` 控制并复用同一 assistant profile（同一 `CODEX_HOME`），官方 `codex` CLI 无法稳定识别并续接同一会话上下文。
+
+### 3.4 记忆原材料来源未收敛
+
+记忆系统需要稳定输入；若 Feishu 和 Codex CLI 的会话采集不统一，记忆质量与可追溯性会持续波动。
+
+## 4. 目标 / 非目标
+
+### 4.1 目标
+
+1. 将产品明确收敛为 CLI-only，对外保留单一入口：`./ally.sh`。
+2. 支持“从 `work-ally` 启动官方 `codex` CLI”并强制复用 assistant 绑定 profile。
+3. 建立 Feishu 与官方 Codex CLI 的同一会话连续体（同一 session 语义，不做摘要复制式伪连续）。
+4. 以 `thread/read(includeTurns=true)` 作为统一会话采集机制，覆盖 Feishu 路径与官方 CLI 路径。
+5. 将会话采集结果统一沉淀到 assistant desk，作为记忆提炼原材料。
+6. 删除桌面端实现与对外口径，避免平行产品线继续演化。
+
+### 4.2 非目标
+
+1. 不在中间层重做一套会话引擎或聊天数据库。
+2. 不实现新的 GUI 入口替代 desktop。
+3. 不在本次引入多机协同、云端托管会话、跨设备自动同步。
+4. 不把记忆系统扩展成“全量知识库平台”；本次只收口“会话原材料 -> desk 记忆资产”。
+5. 不再推进 Codex Hook 采集方案。
+
+## 5. 产品定义与用户路径
+
+### 5.1 产品定义
+
+`work-ally` 提供三件事：
+
+1. 渠道互通：Feishu 消息与 Codex 执行链路互通。
+2. 会话连续：Feishu 与官方 `codex` CLI 指向同一 assistant profile 与同一会话语义。
+3. 记忆沉淀：会话原材料统一汇总到 assistant desk 并可持续提炼。
+
+### 5.2 主路径 A：用户在 Feishu 发起并持续会话
+
+1. 用户在 Feishu 与 assistant 对话。
+2. `work-ally` 调用官方 Codex runtime 处理。
+3. 在关键时机（如 final reply 后）与定时任务中，对当前 thread 执行 `thread/read`。
+4. 仅抽取 user/assistant 对话正文并按天+thread 覆盖写原材料。
+
+### 5.3 主路径 B：用户从 work-ally 启动官方 codex CLI 接续同一会话
+
+1. 用户执行 `ally codex --assistant <name> [codex args...]`。
+2. `work-ally` 注入该 assistant 的 `CODEX_HOME/profile` 后启动官方 `codex`。
+3. 用户在官方 CLI 中继续同一 assistant 会话。
+4. 后台定时同步继续拉取该 thread 的完整会话正文。
+
+### 5.4 主路径 C：用户从官方 codex CLI 回到 Feishu
+
+1. 用户结束 CLI 操作后回到 Feishu。
+2. 后续消息仍命中同一 assistant 与同一会话连续体。
+3. 用户不需要迁移聊天记录，也不需要手工导出上下文。
+
+### 5.5 关键异常路径
+
+1. `thread/read` 临时失败：会话处理继续，下一次定时/关键时机补拉。
+2. profile 不匹配：拒绝启动并提示必须通过 `ally codex` 启动，避免产生分叉会话。
+3. 会话映射缺失：允许新会话启动，但明确标记为“新会话，不是续接”。
+
+## 6. 机制设计
+
+### 6.1 capability 分类（Core / Hybrid / Skill）
+
+本能力定义为 **Core**。
+
+原因：
+
+1. 它改变产品主语义（入口、会话真相、默认行为）。
+2. 它跨越 `internal/`、`bridge/`、`runtime/` 与文档口径。
+3. 它必须始终生效，不是按需触发的 workflow，不适合作为 Skill。
+
+### 6.2 核心对象
+
+1. `AssistantProfile`：assistant 绑定的 profile 真相，至少包含 `assistant_home`、`codex_home`、`workspace_root`。
+2. `SessionBinding`：外部会话（Feishu）与官方会话标识（Codex）之间的绑定关系。
+3. `SessionMaterial`：由 `thread/read` 拉取并归一化后的会话原材料事件。
+
+### 6.3 命令面
+
+1. 正式入口：`ally codex --assistant <name> [codex args...]`。
+2. 兼容：`ally handoff codex ...` 保留为兼容别名。
+3. 新增：`ally thread-sync [--thread <threadId>] [--json]`，用于手动触发 thread 拉取。
+
+### 6.4 采集机制（Thread Read Pull）
+
+1. 统一来源：只通过 `thread/read(includeTurns=true)` 获取会话数据。
+2. 统一过滤：仅保留 `userMessage` 与 `agentMessage`。
+3. 统一落盘：按天目录 + thread 文件覆盖写，目录结构：
+   - `.system/archive/YYYY/MM/DD/<threadId>.ndjson`
+4. 覆盖策略：每次同步对目标 thread 的目标日期文件执行完整替换，避免增量漂移。
+
+### 6.5 同步触发策略
+
+1. 定时同步：默认每小时同步一次所有“未归档且未关闭”的 work sessions。
+2. 回复后同步：发送 final reply 后，立即同步当前 thread。
+3. `/new` 前同步：创建新 thread 前，先同步当前 thread。
+4. 记忆整理前同步：memory digest routine 执行前先做一次全量同步。
+
+### 6.6 会话与记忆管线
+
+1. 记忆提炼只消费 thread pull 产物，不再依赖中间层消息事件落库。
+2. daily digest 仅扫描当天目录下 thread 文件。
+3. 记忆写回继续遵守 assistant desk 边界（`MEMORY.md` 等长期资产可审计、可版本化）。
+
+### 6.7 Desktop 退场合同
+
+1. 删除 `desktop/` 目录与对应测试、构建、发布脚本。
+2. README、DASHBOARD、quickstart 文档改为 CLI-only 口径。
+3. 删除或归档 desktop 相关 planning/implementation 文档，避免继续作为现行路线被引用。
+
+## 7. Scope / Phase
+
+### Phase 1：语义收敛与入口收口
+
+交付：
+
+1. 发布 CLI-only 产品定义与文档口径。
+2. 新增 `ally codex` 正式命令入口。
+3. desktop 能力下线并移除对外入口。
+
+### Phase 2：会话采集统一（Thread Read Pull）
+
+交付：
+
+1. `thread/read` 统一采集管线。
+2. 定时 + 关键时机补拉策略。
+3. `.system/archive/YYYY/MM/DD/<threadId>.ndjson` 覆盖写合同。
+
+### Phase 3：记忆消费收口
+
+交付：
+
+1. 记忆流水线统一消费 thread pull 材料。
+2. assistant desk 记忆资产持续更新并可追溯来源。
+
+## 8. 验收标准
+
+### 8.1 功能验收
+
+1. 用户可仅通过 `./ally.sh` 完成 setup/start/status/logs/codex/thread-sync 主路径。
+2. 执行 `ally codex --assistant <name>` 时，实际使用该 assistant 注册的 `codex_home`。
+3. 用户在 Feishu 与官方 CLI 间切换时，会话可续接且材料持续同步。
+4. `.system/archive/` 中只保留 thread pull 产物，不再写入中间层消息增量流水。
+5. desktop 相关入口、构建、发布不再出现在 shipped 文档与主脚本。
+
+### 8.2 回归验收
+
+1. `bash -n ally.sh`。
+2. 相关 `internal/` shell 脚本语法校验。
+3. `tests/shell/assistant.sh` 与 handoff/continuity 回归通过。
+4. 至少一条“重启后发送普通消息仍可继续处理”的自动化或人工闭环。
+5. `./ally.sh help` smoke 通过，且无 desktop 入口文案。
+
+## 9. 风险 / 假设 / 待决问题
+
+### 9.1 风险
+
+1. `thread/read` 在个别状态下不可用（如首条消息前），可能导致短窗口延迟。
+2. 若只同步 active thread 会漏多 thread；本方案通过“同步所有活跃 work sessions”规避。
+3. 迁移期间若旧 archive 与新 archive 混读，可能造成认知混乱。
+
+### 9.2 假设
+
+1. 官方 Codex CLI 继续作为唯一会话执行真相源。
+2. assistant profile 中的 `codex_home` 可稳定复用并能读取 thread。
+3. 用户接受 CLI-only 入口，不再依赖 desktop 控制面。
+
+### 9.3 待决问题
+
+1. 历史 archive 的迁移与清理策略（是否做一次性迁移脚本）。
+2. thread 文件是否需要额外索引（如最近更新时间索引）以加速大规模扫描。
+3. 对于超长 thread 的读取成本控制（按需分段 vs 全量读取）后续优化策略。