work-ally 0.2.0-alpha.1

package/docs/planning/SPEC-feishu-reaction-shortcuts.md

@@ -0,0 +1,282 @@
+# Feishu Reaction Shortcuts Spec
+
+## Status
+
+- Target project: `work-ally`
+- Audience: implementation engineer
+- Scope: Feishu channel only
+- Goal: support a small set of emoji reactions as deterministic short-text feedback inputs
+
+## Summary
+
+This spec defines a narrow feature for Feishu reactions:
+
+- only a small whitelist of reactions is supported
+- each supported reaction maps to one fixed short text input
+- unsupported reactions are blocked in the bridge layer
+- unsupported reactions trigger a short system reply explaining which reactions are supported
+
+This is intentionally not an open-ended intent-recognition feature.
+
+The product goal is to let users give very lightweight feedback from Feishu, especially on mobile, without typing a full message.
+
+## Problem
+
+Feishu supports reacting to a message with an emoji. This is a convenient user action, but `work-ally` currently does not treat reaction events as inbound conversational input.
+
+For the intended use case, the important part is not the emoji itself. The important part is the lightweight semantic feedback behind it, for example:
+
+- `OK` means “continue”
+- `THUMBSUP` means “agree” or “acknowledged”
+
+If we try to interpret all reactions freely, the feature becomes ambiguous and hard to control.
+
+So the correct design is to constrain it aggressively.
+
+## Product Decision
+
+This feature should be implemented as a fixed whitelist of reaction shortcuts.
+
+Behavior rules:
+
+1. Only reactions in the whitelist are accepted.
+2. Each accepted reaction maps to one fixed short text.
+3. Only reactions placed on assistant-authored messages are handled.
+4. Unsupported reactions do not reach Codex.
+5. Unsupported reactions produce a short system message telling the user which reactions are supported.
+6. Only reaction creation events are handled. Reaction deletion events are ignored.
+
+## Non-goals
+
+This feature does not attempt to:
+
+- infer open-ended user intent from arbitrary emojis
+- support every Feishu emoji
+- preserve reaction IDs in the prompt
+- expose internal message IDs to Codex
+- treat reactions as rich structured prompt objects
+
+This is a narrow input shortcut feature, not a general emoji-understanding layer.
+
+## Why This Feature Exists
+
+### 1. Very low-friction feedback
+
+On Feishu mobile, tapping a reaction is faster than typing a message.
+
+This is useful for tiny feedback actions such as:
+
+- continue
+- confirm
+- acknowledge
+
+### 2. Deterministic behavior
+
+By limiting the feature to a few explicit mappings, we avoid a fragile “guess the meaning of the emoji” design.
+
+### 3. Clear product boundary
+
+If a user uses an unsupported emoji, the system should not invent meaning. It should stop at the bridge layer and explain the supported set.
+
+## Supported Reaction Set
+
+The first version should support only a very small whitelist.
+
+Recommended initial mapping:
+
+- `OK` -> `继续`
+- `THUMBSUP` -> `认同`
+- `CHECK_MARK` -> `已确认`
+
+Exact Feishu emoji type names must be validated against the SDK/platform event payloads during implementation.
+
+If the platform uses different canonical names, keep the product meaning the same and normalize the platform names in the adapter layer.
+
+## User-Facing Behavior
+
+### Supported reaction on an assistant message
+
+When a user adds a supported reaction to an assistant-authored message:
+
+- the bridge accepts the reaction event
+- the bridge converts it into one fixed short text input
+- that short text is sent into the normal Codex inbound path
+
+Examples:
+
+- user reacts with `OK` -> Codex receives `继续`
+- user reacts with `THUMBSUP` -> Codex receives `认同`
+- user reacts with `CHECK_MARK` -> Codex receives `已确认`
+
+### Unsupported reaction on an assistant message
+
+When a user adds an unsupported reaction to an assistant-authored message:
+
+- the bridge does not send anything to Codex
+- the bridge sends a short system reply in Feishu, for example:
+
+```text
+当前只支持这些表情反馈：OK、THUMBSUP、CHECK_MARK。
+```
+
+### Reaction on a non-assistant message
+
+If the reaction target was not authored by the assistant:
+
+- ignore the event
+- do not send anything to Codex
+- do not send any reply unless product explicitly wants that later
+
+## Technical Route
+
+## Step 1. Subscribe to Feishu reaction-created events
+
+The Feishu adapter currently handles normal message events but not reaction-created events.
+
+Implementation should add support for:
+
+- `im.message.reaction.created_v1`
+
+Reaction deletion events should be ignored in the first version.
+
+## Step 2. Verify that the reacted message belongs to the assistant
+
+Before mapping the reaction to text, the bridge must verify that the target message was authored by the assistant.
+
+This is important because the feature is meant to be a feedback shortcut to the assistant, not a general reaction listener for all chat activity.
+
+Recommended implementation pattern:
+
+- fetch the target message from Feishu using the reacted message ID
+- inspect sender metadata
+- continue only if the target message is assistant-authored
+
+This is an internal bridge concern. Do not expose message IDs to Codex.
+
+## Step 3. Normalize supported reactions through a fixed mapping table
+
+Implement a small mapping table in the Feishu adapter layer, for example:
+
+```text
+OK -> 继续
+THUMBSUP -> 认同
+CHECK_MARK -> 已确认
+```
+
+Only exact whitelist entries are accepted.
+
+If the reaction emoji is not in the mapping table, treat it as unsupported.
+
+## Step 4. Convert supported reactions into plain inbound text
+
+For supported reactions, do not build a complex prompt object.
+
+Just convert the reaction into a normal short inbound text message and let the rest of the pipeline behave as usual.
+
+That means the feature should integrate with the existing receiver path as if the user had typed the mapped phrase manually.
+
+## Step 5. Handle unsupported reactions in the bridge, not in Codex
+
+Unsupported reactions should never be forwarded to Codex.
+
+Instead, the bridge should send a short status/system reply explaining the supported set.
+
+This keeps the feature deterministic and avoids sending meaningless emoji events into model context.
+
+## Recommended Internal Shape
+
+The implementation may synthesize an `InboundMessage` internally for supported reactions, but the synthetic content should remain simple.
+
+For example, a supported `OK` reaction may internally become an inbound message whose `text` is simply:
+
+```text
+继续
+```
+
+No internal message ID or reaction ID should be included in the text given to Codex.
+
+## Prompt Contract
+
+Codex should receive only the mapped short text.
+
+Examples:
+
+- `继续`
+- `认同`
+- `已确认`
+
+This is intentionally simple.
+
+The bridge should not tell Codex things like:
+
+- reaction ID
+- Feishu message ID
+- raw emoji type name unless that is the final user-facing mapped phrase
+
+## Acceptance Criteria
+
+- `work-ally` listens for Feishu reaction-created events
+- only reactions on assistant-authored messages are eligible for handling
+- supported reactions are mapped deterministically to one fixed short text each
+- supported reactions are forwarded into the normal inbound conversation path as plain text
+- unsupported reactions are blocked before Codex
+- unsupported reactions trigger a short system reply listing the supported reactions
+- reaction deletion events are ignored
+- no internal message IDs are included in Codex prompt input for this feature
+
+## Testing Guidance
+
+### Unit tests to add or revise
+
+- Feishu adapter tests for reaction-created events
+  - supported reaction on assistant message -> forwarded as mapped text
+  - unsupported reaction on assistant message -> blocked and system reply emitted
+  - supported reaction on non-assistant message -> ignored
+  - reaction deletion event -> ignored
+
+- normalization or helper tests for reaction mapping
+  - exact emoji type mapping
+  - unsupported emoji fallback path
+
+- receiver-level tests if synthetic inbound events are reused
+  - mapped text reaches the same turn-processing path as normal user text
+
+### Manual verification checklist
+
+- react with `OK` to an assistant message and verify the assistant receives `继续`
+- react with `THUMBSUP` to an assistant message and verify the assistant receives `认同`
+- react with `CHECK_MARK` to an assistant message and verify the assistant receives `已确认`
+- react with an unsupported emoji and verify a short support-message is returned
+- react to a user-authored message and verify nothing is forwarded to Codex
+
+## Risks And Tradeoffs
+
+### 1. Emoji naming mismatch
+
+Feishu event payload names may not exactly match the human-facing labels in this spec.
+
+Implementation must normalize platform names in the adapter layer and keep product semantics stable.
+
+### 2. Chat noise from unsupported reactions
+
+If users repeatedly send unsupported reactions, the bridge may emit repeated support messages.
+
+The first version can accept this behavior if it remains simple, but the implementation engineer may optionally add lightweight dedupe or cooldown behavior later if needed.
+
+### 3. Semantic narrowness is intentional
+
+This design deliberately supports only a few fixed meanings. That is a feature, not a bug.
+
+The goal is predictable shortcut input, not comprehensive emoji understanding.
+
+## Final Recommendation
+
+Implement this feature as a strict whitelist-based shortcut system.
+
+The product rule should be:
+
+- supported reaction on assistant message -> translate to one fixed short text and pass to Codex
+- unsupported reaction -> stop in the bridge and tell the user which reactions are supported
+- reaction on non-assistant message -> ignore
+
+This gives `work-ally` a simple, low-risk, high-convenience feedback mechanism without introducing ambiguous emoji interpretation into the assistant pipeline.

package/docs/planning/SPEC-local-stable-release-boundary.md

@@ -0,0 +1,166 @@
+# SPEC: 本机 Stable Release 边界
+
+状态：Draft / Ready for implementation
+
+## 背景
+
+`work-ally` 当前既是产品源码仓库，也是日常被 `ally` 命令直接消费的实现体。
+
+这在内部打磨阶段会产生一个明确痛点：
+
+- 同一台机器上，用户可能同时运行多个 assistant
+- 维护者在源码仓库里直接改代码、联调、自测
+- 但默认 `ally` 入口如果直接指向这份源码，那么别的 assistant 也可能被动吃到未发布改动
+
+这会让“开发态”和“稳定使用态”混在一起，伤害默认入口的稳定性。
+
+## 问题定义
+
+当前缺少一个足够轻量的本地发布边界：
+
+- 维护者改源码，不应自动影响默认 `ally` 命令
+- 只有当某版代码已经自测通过、确认可交付时，才应提升为默认稳定版本
+- 用户不应该被迫理解复杂的构建、打包、端口、环境切换概念
+
+## 目标
+
+1. 给 `ally` 建立一个本机 stable release 概念
+2. 默认 `ally` 入口优先使用 stable release，而不是正在变化的源码树
+3. 维护者在源码树里改完并验证后，可用一个简单动作把当前版本提升为 stable
+4. 已经运行中的 assistant 不因源码仓库变化而被动热切换
+5. `ally status` 能明确显示当前处于 dev 还是 stable，以及对应实现路径
+
+## 非目标
+
+- 不引入复杂构建系统
+- 不做多版本发布管理 UI
+- 不做远程包仓库或正式安装器
+- 不要求用户理解“编译产物”细节
+- 不在本次解决跨机器升级分发
+
+## 设计原则
+
+- 优先做“本机稳定副本”，不做重量级打包
+- 优先复用现有 shell / node 运行方式，不引入第二套执行模型
+- 默认稳定，显式发布
+- 用户面对的心智模型尽量简单：
+  - 开发者改源码
+  - 确认可发后执行 `ally release`
+  - 普通 `ally` 继续稳定使用
+
+## 方案
+
+### 1. 引入 stable release 目录
+
+默认 stable release 放在：
+
+- `~/.work-ally/releases/stable/`
+
+这里存放一份可运行的本机稳定副本。
+
+### 2. 默认入口优先使用 stable release
+
+默认情况下，`ally` 命令优先解析到 stable release。
+
+只有以下场景才显式使用源码树：
+
+- 设置了 `WORK_ALLY_SOURCE_DIR`
+- 维护者正在源码树里执行 `ally.sh ...`
+- 维护者执行 `ally release`
+
+### 3. 引入显式发布命令
+
+新增：
+
+```bash
+ally release
+```
+
+语义：
+
+- 把当前源码树复制为新的 stable release
+- 安装 release 所需依赖
+- 写入最小 release manifest
+- 替换旧的 `stable` 副本
+
+这是唯一的“提升默认版本”动作。
+
+### 4. 运行态不自动热切换
+
+即使执行了 `ally release`：
+
+- 已经在运行的 assistant 继续跑当前进程
+- 不自动对整机所有 assistant 做热切换
+- 哪个项目需要切到新版，由维护者显式 `ally restart` 或下次 `ally start` 生效
+
+### 5. 状态可见性
+
+`ally status` 至少新增：
+
+- `release channel`
+- `implementation`
+- 若当前实现来自 stable release，则显示 release manifest 里的：
+  - `release updated at`
+  - `release source`
+  - `release commit`
+  - `release source dirty`
+
+## 用户路径
+
+### 普通用户
+
+```bash
+ally start
+ally status
+```
+
+不需要理解源码树或发布目录。
+
+### 维护者
+
+```bash
+# 1. 在源码树里开发
+npm test
+
+# 2. 用源码树联调
+WORK_ALLY_SOURCE_DIR=$PWD ally start
+
+# 3. 确认可发
+ally release
+
+# 4. 默认 stable ally 生效
+ally status
+```
+
+## 验收标准
+
+1. 默认 `ally` 入口优先使用 `~/.work-ally/releases/stable/`
+2. 在源码树里持续改动时，不会自动影响默认 stable 入口
+3. 执行 `ally release` 后，stable release 会被新版本替换
+4. `ally status` 能看到 release channel 与 implementation 路径
+5. stable release 存在 manifest，能追溯来源源码与提交
+6. 文档明确区分开发态与 stable release
+7. shell 回归覆盖默认入口、release 和 status 可见性
+
+## 风险与取舍
+
+### 风险 1：增加一个“副本目录”概念
+
+这是新增概念，但它换来的收益很明确：把“正在开发的源码”与“默认可用版本”隔离开。
+
+### 风险 2：用户可能忘记 release
+
+这是预期成本，但可以通过文档和 `ally status` 的可见性降低困惑。
+
+### 风险 3：stable release 不是严格意义上的编译产物
+
+这是刻意取舍。当前阶段不需要重量级 build artifact；一份可运行的本机稳定副本已经足够解决主要痛点。
+
+## 结论
+
+本期不做复杂 release 系统，只做一个最小闭环：
+
+- 源码树持续开发
+- stable release 保持默认稳定
+- `ally release` 作为唯一提升动作
+- `ally status` 负责把当前边界讲清楚