work-ally 0.2.0-alpha.1

package/docs/completed/FEATURE-feishu-markdown-and-reply-support.md

@@ -0,0 +1,327 @@
+# Feishu Markdown Rendering And Reply Context
+
+## Status
+
+- Target project: `work-ally`
+- Audience: implementation engineer
+- Scope: Feishu channel only
+- Status: implemented in current branch
+- Goal: define two concrete features for the next implementation pass
+
+## Summary
+
+This document defines two Feishu-facing features for `work-ally`:
+
+1. Markdown-first outbound rendering for AI replies
+2. Reply-context extraction for inbound Feishu replies
+
+Both features are motivated by a gap between the current `work-ally` implementation and the newer Feishu integration patterns already proven in OpenClaw.
+
+The key conclusion is:
+
+- Feishu output should no longer default to plain text for normal model replies.
+- When a user replies to a previous Feishu message, `work-ally` should fetch the replied message and pass its plain-text body into the Codex prompt context.
+
+## Background
+
+Historically we treated Feishu bot messages as if they could not reliably render Markdown, so `work-ally` built a downgrade layer that converts model output into plain text and uses `interactive` cards only for a few special cases.
+
+After inspecting OpenClaw, that assumption is no longer sufficient.
+
+OpenClaw demonstrates that Feishu-side Markdown rendering is practical by using Feishu-supported rich message types instead of raw text messages:
+
+- `post` message payloads with `tag: "md"`
+- `interactive` card payloads with `tag: "markdown"`
+
+OpenClaw also demonstrates that reply context is recoverable by fetching the replied message via the Feishu message API and extracting plain text from the original message body.
+
+## Current `work-ally` State
+
+### Outbound rendering
+
+Current rendering is centered in `bridge/src/channels/feishu/formatter.ts`.
+
+Today the implementation behaves like this:
+
+- plain replies are normalized and sent as `text`
+- headings, fenced code, and inline code are downgraded to readable plain text
+- tables and system notices are routed to `interactive` cards
+
+Key references:
+
+- `work-ally/bridge/src/channels/feishu/formatter.ts`
+- `work-ally/bridge/src/channels/feishu/adapter.ts`
+- `work-ally/tests/unit/channel/formatter.test.mjs`
+- `work-ally/tests/unit/channel/feishu-adapter-outbound.test.mjs`
+
+This means the current system already has a unified rendering entrypoint, but the default output target is still plain text rather than Feishu Markdown-capable rich messages.
+
+### Inbound reply handling
+
+Current inbound normalization only extracts the current message body and does not elevate Feishu reply metadata into the normalized message contract.
+
+Key references:
+
+- `work-ally/bridge/src/channels/feishu/normalize.ts`
+- `work-ally/bridge/src/types.ts`
+- `work-ally/bridge/src/receiver.ts`
+
+Today `work-ally` does not:
+
+- preserve `parent_id`
+- preserve `root_id`
+- fetch the replied message body
+- append reply-body context into the prompt sent to Codex
+
+## OpenClaw Reference Findings
+
+### A. Markdown rendering
+
+OpenClaw uses two outbound forms.
+
+#### 1. `post` rich-text message with Markdown node
+
+Reference:
+
+- `.cache/openclaw/extensions/feishu/src/send.ts`
+
+Relevant logic:
+
+- `buildFeishuPostMessagePayload(...)` builds `msg_type: "post"`
+- payload contains `zh_cn.content` with `{ tag: "md", text: messageText }`
+
+This is the important correction to the old assumption: OpenClaw is not relying on plain `text` messages for Markdown rendering.
+
+#### 2. `interactive` card with Markdown element
+
+Reference:
+
+- `.cache/openclaw/extensions/feishu/src/send.ts`
+- `.cache/openclaw/extensions/feishu/src/outbound.ts`
+- `.cache/openclaw/extensions/feishu/src/reply-dispatcher.ts`
+- `.cache/openclaw/extensions/feishu/src/streaming-card.ts`
+
+Relevant logic:
+
+- `buildMarkdownCard(...)` builds card schema with `tag: "markdown"`
+- outbound routing chooses card rendering for explicit card mode or markdown-heavy content such as tables/code blocks
+- streaming replies also use card-based markdown updates
+
+For `work-ally`, streaming is not required for this feature set. The main takeaway is that `interactive` cards are a valid, proven Feishu Markdown carrier.
+
+### B. Reply-context extraction
+
+Reference:
+
+- `.cache/openclaw/extensions/feishu/src/send.ts`
+- `.cache/openclaw/extensions/feishu/src/post.ts`
+- `.cache/openclaw/extensions/feishu/src/bot.ts`
+
+Relevant logic:
+
+- `getMessageFeishu(...)` fetches message details through `client.im.message.get`
+- `parseQuotedMessageContent(...)` extracts plain text from `text`, `post`, and `interactive`
+- inbound bot logic reads `parent_id`, fetches the quoted message, and injects the extracted body into prompt context as `ReplyToBody`
+
+This is the exact pattern we want to reuse conceptually in `work-ally`.
+
+## Feature 1: Markdown-First Feishu Rendering
+
+## Problem
+
+Codex model replies are already Markdown-shaped. The current `work-ally` implementation strips or downgrades much of that structure before delivery, which reduces readability and wastes Feishu’s richer message capabilities.
+
+## Goal
+
+Treat model output as Markdown by default and render it in Feishu through rich message types instead of downgrading normal replies to plain text.
+
+## Desired UX
+
+- headings should remain visually structured
+- lists should stay lists
+- links should remain links
+- code blocks should render as code blocks when practical
+- tables should render as tables or as the best supported rich equivalent
+
+## Recommended design
+
+Keep one outbound rendering entrypoint, but make it Markdown-first.
+
+Suggested model:
+
+1. Keep a single renderer entry such as `renderFeishuMessages(markdown)`.
+2. Stop treating plain `text` as the default reply container for normal model output.
+3. Internally choose the Feishu carrier based on content shape:
+   - normal Markdown: use `post` with `tag: "md"`
+   - tables, approval/system cards, or content requiring structured blocks: use `interactive`
+4. Keep the adapter thin. It should send already-rendered payloads, not interpret Markdown itself.
+
+## Important implementation note
+
+Do not collapse everything into one single Feishu carrier type.
+
+We want one rendering pipeline, not one message type.
+
+The correct simplification is:
+
+- one Markdown-first rendering contract
+- two internal outbound carriers when needed
+
+This preserves simplicity without forcing all traffic through `interactive` cards.
+
+## Suggested contract changes
+
+`FeishuRenderedMessage` should likely evolve from:
+
+- `text`
+- `interactive`
+
+to something closer to:
+
+- `post`
+- `interactive`
+- optional retained `text` only for true low-format cases if still needed
+
+## Acceptance criteria
+
+- a normal multi-paragraph Markdown reply is no longer downgraded to plain `text`
+- headings and links survive as Feishu-rendered rich content
+- fenced code blocks render through a Feishu rich-message path instead of plain-text degradation when supported by the chosen carrier
+- markdown tables no longer require text fallback as the primary path
+- approval/system messages continue to work
+- long replies still chunk safely
+
+## Feature 2: Reply-Context Support For Feishu Replies
+
+## Problem
+
+When a user replies in Feishu to a previous AI message, `work-ally` currently does not carry the replied message body into the prompt context. The model therefore loses an important local reference and may not understand which prior point the user is asking about.
+
+## Goal
+
+When an inbound Feishu message is a reply to an earlier message, fetch the replied message, extract its plain-text content, and include that content in the prompt sent to Codex.
+
+## Non-goal
+
+Do not reconstruct the original rich structure.
+
+We only need:
+
+- replied message id
+- optional topic/root id
+- extracted plain-text body
+
+This is enough to support the user experience of “I am asking about that earlier reply.”
+
+## Recommended design
+
+### Step 1. Extend normalized inbound contract
+
+Add Feishu-relevant reply fields to `InboundMessage`, for example:
+
+- `replyToMessageId?: string | null`
+- `rootMessageId?: string | null`
+- `replyToText?: string | null`
+
+Exact field names can vary, but reply metadata must become part of the normalized bridge contract rather than remaining buried in raw channel payloads.
+
+### Step 2. Preserve reply metadata during normalization
+
+In `bridge/src/channels/feishu/normalize.ts`, read reply metadata from the Feishu event, especially:
+
+- `parent_id`
+- `root_id`
+
+These should be lifted into the normalized message object.
+
+### Step 3. Add Feishu-side message fetch helper
+
+Add channel-local helper logic in the Feishu adapter layer to fetch a message by message id using the Feishu SDK.
+
+This helper should extract plain text from at least:
+
+- `text`
+- `post`
+- `interactive`
+
+The extraction goal is readability, not exact reconstruction.
+
+### Step 4. Enrich prompt context before runtime dispatch
+
+Before sending the final prompt to Codex, append reply context in a stable, explicit way, for example:
+
+```text
+User is replying to a previous Feishu message.
+
+Replied message body:
+<plain text extracted from parent message>
+
+Current user message:
+<current inbound text>
+```
+
+The exact envelope can vary, but the prompt should make the relationship explicit.
+
+## Acceptance criteria
+
+- if a user replies to an earlier Feishu message, the normalized inbound message includes the reply target id
+- `work-ally` fetches the replied message body before runtime dispatch when possible
+- if the replied message is `text`, `post`, or `interactive`, the fetched body is converted to readable plain text
+- the prompt sent to Codex includes the replied message body in a stable format
+- if fetch fails, the current user message still proceeds normally without breaking the turn
+
+## Recommended Implementation Order
+
+1. Land reply metadata in normalized inbound contracts.
+2. Land message-fetch helper plus text extraction.
+3. Plumb reply-body context into runtime prompt construction.
+4. Replace Markdown downgrade-first rendering with Markdown-first rich rendering.
+5. Update adapter and unit tests.
+
+Reply-context support is lower risk and directly improves conversation quality, so it is a good first implementation step.
+
+## Testing Guidance
+
+### Unit tests to add or revise
+
+- `work-ally/tests/unit/channel/formatter.test.mjs`
+  - assert normal Markdown now renders to rich outbound payloads rather than downgraded plain text
+  - assert table/code/link cases route to the expected Feishu carrier
+
+- `work-ally/tests/unit/channel/feishu-adapter-outbound.test.mjs`
+  - assert adapter sends `post` or `interactive` for normal final replies under the new renderer
+  - keep approval/system-card coverage intact
+
+- new Feishu reply parsing tests
+  - normalize `parent_id` and `root_id`
+  - verify replied-message fetch is triggered
+  - verify fetched `text/post/interactive` content becomes readable plain text
+
+- receiver or prompt-construction tests
+  - verify reply-body context is appended to the final runtime input
+
+### Manual verification checklist
+
+- ask for a normal Markdown answer with headings and links
+- ask for a code-heavy answer with fenced code blocks
+- ask for a table-heavy answer
+- in Feishu, reply to an earlier AI answer with “你说的第二点再展开一下”
+- verify the model correctly interprets which prior message is being referenced
+
+## Risks And Constraints
+
+- Feishu rich message capabilities differ by carrier type, so the renderer must choose the carrier intentionally.
+- Reply-body fetch must be best-effort. Failure to fetch must not fail the turn.
+- Quoted-message support should stay content-first. Do not add structure-preservation scope unless later demanded by product needs.
+- Chunking logic must be revalidated after the outbound rendering change.
+
+## Final Recommendation
+
+Implement both features, with these guiding rules:
+
+- use one Markdown-first rendering pipeline for all model output
+- allow that pipeline to choose between Feishu rich carriers internally
+- support Feishu reply context by fetching the parent message and extracting plain text only
+- do not add streaming or edit support as part of this scope
+
+That gives `work-ally` a cleaner delivery path and a better multi-turn remote conversation experience without turning the Feishu bridge into a second agent system.

package/docs/completed/README.md

@@ -0,0 +1,21 @@
+# Completed Topics
+
+这里收已经完成、已落地、已不应再按“待实现 spec”理解的专题文档。
+
+放进这个目录，表示至少满足下面两条：
+
+1. 用户路径或 shipped model 已经成立
+2. 当前继续讨论时，应默认把它当成已交付基线，而不是待做方案
+
+这个目录不是历史归档仓库。
+
+它的作用是避免两种错误：
+
+- 已做完的功能还继续被当成 planning
+- 新 feature 讨论时重复推翻已落地能力
+
+当前这里主要放：
+
+- 已完成专题 spec
+- 已落地功能的专题回写
+- 产品负责人确认已收口的专题说明

package/docs/completed/SPEC-approval-autonomy-and-safe-defaults.md

@@ -0,0 +1,205 @@
+# Approval Autonomy And Safe Defaults
+
+## Status
+
+- Target project: `work-ally`
+- Audience: product owner / implementation engineer
+- Scope: runtime approval boundary, self-validation flow, human-in-the-loop contract
+- Status: shipped baseline / 2026-03-15
+- Goal: stop routing low-risk local self-validation through repeated user approvals while keeping real-risk actions under explicit human control
+
+## Summary
+
+当前审批机制的根问题不是“卡片文案不够好”，而是**审批边界定错了**。
+
+对 `work-ally` 这种由 assistant 兼任产品和开发的长期协作场景，很多动作本质上属于：
+
+- 本地阅读
+- 本地测试
+- 当前仓库内改动
+- 当前仓库内 commit
+- assistant desk 根目录内的记忆/文档维护
+
+这些动作如果每一步都要求飞书用户手动同意，会把用户拖进 assistant 的自测过程里，造成高频、低价值、打断式参与。
+
+这条 spec 的核心判断是：
+
+> 默认不该让用户审批 assistant 自己的低风险本地验证流程；用户只应被拉入真正需要人类拍板的边界动作。
+
+## Background
+
+近期真实对话中已经反复暴露出一个协作问题：
+
+- assistant 在修复 bug、跑聚焦测试、提交代码时，频繁向飞书用户发起审批
+- 用户被迫反复点“同意”，哪怕动作只是当前仓库内的自测和 commit
+- 这让产品负责人兼开发者的工作流变成“每一步都要等用户当临时操作员”
+
+用户已经明确指出：
+
+1. 这类审批体验非常蠢
+2. assistant 需要先反思哪些动作根本不该找用户审批
+3. 如果确实存在不能自主决策的边界，也应把协作合同说清楚，而不是默认把所有动作都抛给用户
+
+## Problem Statement
+
+当前问题有三层。
+
+### 1. 低风险动作被错误归类为人工审批项
+
+例如：
+
+- 查看日志
+- 运行本地测试
+- `git add`
+- 当前仓库内 `git commit`
+- assistant desk 根目录内的稳定文档更新
+
+这些动作虽然技术上属于 runtime approval，但从产品语义上看，并不都应该要求飞书用户逐条批准。
+
+### 2. 审批边界站在 runtime 视角，而不是站在协作关系视角
+
+runtime 看到的是：
+
+- 命令执行
+- 文件修改
+
+但用户真正关心的是：
+
+- 你是不是在做正常自测
+- 你是不是在改当前项目
+- 你是不是要碰项目外、外部系统、破坏性动作或发布动作
+
+如果产品不把这层翻译清楚，审批就会持续过度触发。
+
+### 3. 用户被卷入 assistant 的内部验证过程
+
+用户应该只在需要人类拍板时参与，而不是在 assistant 自己的修复闭环里扮演按钮操作员。
+
+## Product Decision
+
+建立一套更贴近协作现实的审批边界：
+
+### A. assistant 可自主决策的动作
+
+默认应允许 assistant 自主完成：
+
+- 当前项目仓库内的读操作
+- 当前项目仓库内的测试、lint、局部验证
+- 当前项目仓库内的非破坏性代码改动
+- 当前项目仓库内的 `git add` / `git commit`
+- assistant desk 根目录内的 `SOUL.md` / `NOW.md` / `MEMORY.md` / `MISTAKES.md` / `journal/` / `conversations/` 等维护动作
+- 为排查当前问题所需的本地日志读取与本地状态检查
+
+### B. 仍需用户参与拍板的动作
+
+默认仍应要求显式人工边界的动作：
+
+- `git push`
+- 发布、部署、重启线上入口或影响真实对话可用性的动作
+- 项目外路径写入
+- 可能破坏数据的动作
+- 外网写操作或外部系统副作用
+- 大范围删除 / 重置 / 覆盖
+- 需要用户亲自参与的真人验收、重启、环境变更
+
+### C. 产品目标
+
+用户不再审批 assistant 的“自测过程”，只审批 assistant 的“风险边界”。
+
+## Goals
+
+1. 减少飞书里低价值审批打断
+2. 让 assistant 可以独立完成修复、自测、提交的基本闭环
+3. 保留真正高风险动作的人类拍板边界
+4. 把“哪些可自决、哪些必须拉人”变成稳定产品合同，而不是临场猜测
+
+## Non-goals
+
+本次不做：
+
+- 完整权限系统重构
+- 一次性解决所有 runtime 原生 approval 类型
+- 自动放开外部副作用写操作
+- 取消所有人工审批
+
+## Scope
+
+V1 先收口三件事：
+
+1. 明确低风险本地动作的产品白名单
+2. 为这类动作提供默认放行或更低摩擦的授权路径
+3. 明确需要用户配合的高风险边界
+
+## Proposed Model
+
+### 1. Local Self-Validation Lane
+
+引入稳定产品判断：
+
+- 当前项目目录
+- 当前 assistant desk
+
+这两个根内的低风险动作，属于 assistant 的自驱工作范围。
+
+应优先支持：
+
+- 无需逐条飞书审批
+- 默认静默自动放行，但在内部状态与 archive 中保持可审计记录
+
+### 2. Human-Gated Lane
+
+以下动作进入人工拍板：
+
+- 发布 / 推送 / 对外副作用
+- 跨项目或跨目录写入
+- 破坏性命令
+- 高成本或不可逆操作
+- 需要用户现实参与的动作（如重启、真人验证）
+
+### 3. Cooperation Contract
+
+如果某动作 assistant 不能自主完成，应明确告诉用户：
+
+- 为什么这步必须你来
+- 你需要做什么
+- 做完后 assistant 会继续什么
+
+而不是简单丢一张 runtime 审批卡让用户自己猜。
+
+## Implementation Direction
+
+优先顺序：
+
+1. 先把产品白名单和高风险边界写清楚
+2. 再决定用哪种工程策略实现
+
+可选实现方向包括：
+
+- 调整 runtime approval policy / trusted boundary
+- 为当前项目与 assistant desk 生成更合理的默认授权配置
+- 针对 `git add` / `git commit` / 本地测试等命令做有限范围的默认放行
+- 在 bridge 层把审批分级，低风险动作走 assistant 自治 lane，高风险动作才出卡
+
+V1 不要求一次定死实现方案，但必须先把产品边界拍板。
+
+## Acceptance Criteria
+
+1. assistant 在当前项目根与 assistant desk 根内做本地修复、自测、改动、提交时，不再频繁要求用户逐条审批
+2. 这类低风险动作默认静默自动放行，不再额外刷“已自动放行”的系统消息
+3. 用户只在高风险、外部副作用或明确需要人类拍板的动作上被拉入
+4. 文档中明确列出：哪些动作 assistant 可直接做，哪些动作必须找用户配合
+5. 用户参与动作时，提示语义从“技术审批”转向“协作边界说明”
+
+## Open Questions
+
+1. `git commit` 是否默认应进入 assistant 自治白名单
+2. 当前 repo + assistant desk 的 trusted / writable / approval 策略，是否应在 setup 时固化生成
+3. 是否需要为“产品负责人兼开发”提供单独的默认审批 profile
+
+## Product Judgment
+
+这不是“优化审批卡文案”的小修。
+
+这是 `work-ally` 的一个核心产品判断：
+
+> assistant 既然承担产品和开发职责，就必须拥有完成低风险本地闭环的默认操作权；否则它就不是负责人，只是一个随时等人点同意的半自动工具。