work-ally 0.2.0-alpha.1

package/docs/completed/SPEC-project-group-chat-human-centered-conversation-mapping.md

@@ -0,0 +1,326 @@
+# SPEC: Project Group Chat With Platform-Scoped Mention Routing
+
+更新时间：2026-03-19  
+状态：Completed  
+Owner：Ally  
+相关文档：
+- `README.md`
+- `PRODUCT.md`
+- `DASHBOARD.md`
+- `docs/user-quickstart.md`
+- `docs/completed/SPEC-group-chat-sender-identity.md`
+
+## 1. Summary
+
+项目群聊 V1 收敛为一个极简模型：
+
+> 一个助理对应一个独立飞书机器人身份；在群里，只有用户显式 `@` 这个机器人时，才会触发这位助理处理消息。
+
+这次不做 `focus`、`/switch`、reply 自动续聊、群级共享 thread、助理间协作，也不增加新的中间层兜底配置。
+
+对同一位助理来说：
+
+- 私聊消息进入它自己的私聊 thread
+- 群里 `@` 它的消息进入它在该群里的群聊 thread
+- 两者属于同一助理，但必须是两个独立 thread
+
+这次实现的关键不是新增一套群聊系统，而是把群聊能力收紧成一个完全依赖飞书平台正确配置的最小模型。
+
+## 2. 背景
+
+当前 `work-ally` 的稳定主线是 Feishu 私聊主闭环。群聊侧虽然已有一层最小显式触发逻辑，但口径仍不够收敛：
+
+- 当前群聊门控还接受“文本像是 `@...` 开头”或“reply bot 消息”这类宽松条件
+- 当前讨论里一度出现了 `focus`、`switch`、本地自检、prompt 清洗等扩张方向
+- 这些方向如果继续进入产品，会让中间层从桥梁逐渐变成群聊状态机
+
+与此同时，已经确定的产品边界很清楚：
+
+1. 一个助理必须对应一个独立机器人身份
+2. 项目群只是前台入口，不是共享脑
+3. 群里只能通过显式 `@` 召唤某一个助理
+4. 私聊入口和群聊入口都属于同一个助理，但必须落到不同 thread
+5. 中间层要坚持 KISS，不为了兜底越界配置而增加长期维护负担
+
+因此，这次要做的不是“把所有异常情况都兜住”，而是把正式支持范围定义清楚，并让实现严格贴着这条边界走。
+
+## 3. 问题定义
+
+### 3.1 项目视图需要收敛，但不能引入共享会话
+
+用户希望把多个助理放进同一个项目群，减少多个私聊窗口的切换成本。
+
+但这不等于要把群本身做成共享 thread。当前真实架构里，每个助理本来就是独立进程、独立 desk、独立 runtime。
+
+### 3.2 群聊触发规则必须和平台权限一致
+
+在飞书平台正确配置下：
+
+- 单聊消息会直接推给对应机器人
+- 群聊里只有 `@机器人` 的消息才会推给对应机器人
+- 如果额外开了“获取群组中所有消息”，才会破坏这个边界
+
+所以产品模型必须基于这条事实，而不是假设所有群消息都会先进入中间层再过滤。
+
+### 3.3 中间层不能为了少数越界场景变厚
+
+如果为了防“用户把平台权限配错”而继续引入：
+
+- 当前机器人自身份配置
+- 群聊 mentions 自检
+- prompt 输入清洗
+- 更多本地兼容分支
+
+那么中间层的复杂度会明显上升，但这些能力都不是主链路必需品。
+
+这不符合当前产品的 KISS 原则。
+
+### 3.4 当前群聊门控仍包含与正式合同冲突的旧路径
+
+当前代码仍接受下面几类群消息：
+
+- 看起来像 `@...` 开头的文本
+- 控制命令
+- reply bot 消息
+
+而最新产品定义已经收敛为：
+
+- V1 只支持飞书平台已正确过滤后的“显式 `@当前机器人` 群消息”
+- reply 但未再次 `@`，不支持
+- 如果用户开启了“获取群组中所有消息”，则超出当前支持范围
+
+## 4. 目标 / 非目标
+
+### 4.1 目标
+
+1. 让多个助理可共存于同一个项目群
+2. 保持人类中心化：群里每次只点名一个助理
+3. 保持架构诚实：一个助理仍然是一个独立进程和独立机器人身份
+4. 让同一助理的私聊入口与群聊入口都能正确路由到各自 thread
+5. 用最小改动把群聊 V1 收成稳定能力
+
+### 4.2 非目标
+
+1. 不做群级共享 thread
+2. 不做 `focus`、`/switch`、默认 assistant 切换
+3. 不做 reply 自动续聊
+4. 不做普通群消息自动触发
+5. 不做助理间协作、互聊、派工或 handoff
+6. 不做额外自身份配置项，例如 `FEISHU_BOT_OPEN_ID`
+7. 不做基于机器人名字的路由或校验
+8. 不做针对 `@当前助理` 的 prompt 文本截断或清洗
+
+## 5. 产品定义与用户路径
+
+### 5.1 一句话定义
+
+`项目群聊` 是多个助理共享的前台入口；用户只有在群里显式 `@` 某个助理对应的机器人时，才算在和这位助理继续该群里的独立 thread。
+
+### 5.2 核心产品定义
+
+1. 一个助理对应一个独立机器人身份
+2. 一个机器人只代表一个助理，不允许多个助理共用同一个机器人
+3. 同一助理可同时拥有多个并行 thread
+4. thread 隔离单位收敛为：`assistant + channel + conversation_id`
+5. 私聊和群聊都是同一助理的入口，但绝不共享同一条 thread
+
+### 5.3 路径 A：私聊助理
+
+例子：
+
+```text
+请帮我整理这个需求
+```
+
+结果：
+
+- 这条消息直接进入该助理的私聊 thread
+- 该 thread 仅对应这条单聊会话
+
+### 5.4 路径 B：在项目群里显式 `@` 助理
+
+例子：
+
+```text
+@Ally 帮我把这个需求整理成 spec
+```
+
+结果：
+
+- 这条消息进入 `Ally` 在该 `group_id` 下的群聊 thread
+- 同一助理的私聊 thread 不受影响
+- 其他助理不会处理这条消息
+
+### 5.5 路径 C：群里普通消息
+
+例子：
+
+```text
+这个事情下周再说
+```
+
+结果：
+
+- 在正式支持边界内，这类消息不会被推送给助理
+- 若用户错误开启“获取群组中所有消息”，则该行为超出当前支持范围
+
+### 5.6 路径 D：reply 助理消息但未再次 `@`
+
+例子：
+
+- 用户回复助理上一条消息，正文是“第二点展开”
+
+结果：
+
+- V1 不支持这条路径
+- 用户需要重新显式 `@` 该助理
+
+## 6. 机制设计
+
+### 6.1 平台前提
+
+飞书平台配置必须满足：
+
+- 订阅事件：`im.message.receive_v1`
+- 开启权限：`读取用户发给机器人的单聊消息`
+- 开启权限：`接收群聊中@机器人消息事件`
+- 不开启权限：`获取群组中所有消息（敏感权限）`
+
+在这套前提下，中间层原则上只会收到：
+
+- 发给当前机器人的单聊消息
+- 群里明确 `@` 当前机器人的消息
+
+### 6.2 中间层职责
+
+中间层这次只承担一件核心工作：
+
+- 把同一助理的不同会话入口正确路由到不同 thread
+
+不额外承担：
+
+- 平台越界配置兜底
+- 当前机器人自身份识别
+- prompt 文本清洗
+- 第二套路由状态管理
+
+### 6.3 会话与 thread 路由模型
+
+对单个助理来说：
+
+- 私聊：`(channel=feishu, dm_conversation_id) -> thread`
+- 群聊：`(channel=feishu, group_conversation_id) -> thread`
+
+当前实现已经有按 `ConversationRef` 建立 / 续用 session 与 thread 的基础能力；本次不新增新的 thread 对象，也不新增跨助理共享状态。
+
+### 6.4 群聊输入边界
+
+V1 对群聊输入的正式合同是：
+
+- 中间层信任飞书平台的事件过滤边界
+- 平台推过来的群聊消息，视为已经满足“显式 `@当前机器人`”前提
+- 不再额外引入 `bot_open_id` 或机器人名字来做本地校验
+
+如果用户主动开启“获取群组中所有消息”，则：
+
+- 该行为超出当前功能支持范围
+- 产品不承诺群聊路由仍然保持正确
+
+### 6.5 `@当前助理` 文本是否截断
+
+V1 不做这件事。
+
+原因：
+
+- 这是轻微噪音，不是主链路问题
+- 为了清洗这点文本再引入输入改写逻辑，不符合 KISS
+- 当前更应优先保持桥梁简单，而不是过度优化 prompt 纯度
+
+## 7. 实现范围
+
+### 7.1 需要修改的模块
+
+#### A. `bridge/src/channels/feishu/adapter.ts`
+
+收紧群聊准入逻辑：
+
+- 去掉“reply bot 消息即可通过”的逻辑
+- 不再把这类本地启发式路径当成正式支持能力
+- 群聊行为收口为：信任飞书平台已做的 `@机器人` 过滤
+
+#### B. `tests/unit/channel/feishu-adapter-inbound.test.mjs`
+
+测试口径改为：
+
+1. 单聊消息可通过
+2. 已被平台过滤后进入 adapter 的群聊消息可通过
+3. group reply bot 但未再次 `@` 不再视为受支持路径
+
+#### C. 文档
+
+实现完成后，按需同步：
+
+- `README.md`
+- `docs/user-quickstart.md`
+- `DASHBOARD.md`
+- `docs/user-quickstart.md`
+
+重点写清：
+
+- 一个助理对应一个独立机器人身份
+- 群聊依赖飞书平台权限正确配置
+- 不支持“获取群组中所有消息”权限下的群聊行为
+
+### 7.2 不需要新增的东西
+
+本次明确不新增：
+
+- `FEISHU_BOT_OPEN_ID`
+- mentions 结构化自检逻辑
+- prompt 清洗逻辑
+- `focus` 状态
+- 群级路由表
+- 助理共享状态存储
+- 群级 thread 对象
+- 基于名字的别名匹配
+
+## 8. 验收标准
+
+1. 一个助理必须绑定一个独立机器人身份。
+2. 同一助理可同时拥有私聊 thread 与群聊 thread，两者互不共享上下文。
+3. 单聊消息会进入该助理自己的私聊 thread。
+4. 群聊功能建立在飞书平台正确权限配置之上，不额外依赖中间层自身份配置。
+5. group reply bot 但未再次 `@`，V1 不再作为受支持路径。
+6. 代码中不再把 reply bot 当作正式群聊准入依据。
+7. 代码中不新增 `FEISHU_BOT_OPEN_ID` 等自身份配置项。
+8. 代码中不新增 prompt 文本截断或清洗逻辑。
+9. 现有 session / thread 模型继续沿用，不引入新的共享状态对象。
+10. 文档中明确写出：若开启“获取群组中所有消息”，则超出当前支持范围。
+
+## 9. 风险 / 假设 / 待决问题
+
+### 9.1 风险
+
+1. 如果用户把飞书权限配错，群聊行为可能超出当前产品合同；这次不在中间层兜底。
+2. 强制每次群里都重新 `@` 会牺牲一点顺滑感，但这是当前阶段主动接受的取舍。
+3. 群消息文本里可能带有 `@当前助理` 字样，但 V1 接受这点轻微 prompt 噪音。
+
+### 9.2 当前假设
+
+1. 用户接受群里每次显式 `@` 助理。
+2. 用户接受“平台配置正确”是当前功能成立的前提。
+3. 当前阶段优先级是简单、稳定、低歧义，而不是更像自然群聊。
+4. 一个助理对应一个机器人身份，这条约束未来也会继续成立。
+
+### 9.3 待决问题
+
+1. README / user-facing quickstart 是否要单独增加“群聊配置前提”小节。
+2. 后续若要支持 reply 自动续聊，应作为 V2 新 spec 单独讨论，不在本次实现中提前埋口子。
+
+## 10. 当前结论
+
+项目群能力的正式方向已经收敛为：
+
+> 一个助理对应一个独立机器人；私聊与群聊 `@` 都是在找同一位助理，但它们必须进入各自独立的 thread。
+
+这次实现不引入新对象，不引入共享状态，也不为了少数越界场景给中间层额外加厚；它只把飞书群聊入口收紧到一个稳定、诚实、可维护的最小模型。

package/docs/completed/SPEC-remove-cli-persona-bootstrap.md

@@ -0,0 +1,201 @@
+# Remove CLI Persona Bootstrap
+
+更新时间：2026-03-21  
+状态：Implemented  
+Owner：Ally  
+相关文档：
+- `docs/planning/SPEC-assistant-persona-bootstrap.md`
+- `docs/user-quickstart.md`
+- `internal/modules/assistant/manage.sh`
+
+## 1. Summary
+
+当前决定撤回 `work-ally` 的 CLI 人设引导能力：删除 `--persona` / `--persona-file`，不再让中间层在 `ally setup` 或 `assistant add|ensure` 时替用户写入 `SOUL.md`。未来的人设编辑只保留两条正式路径：桌面端直接编辑，或由偏程序员的用户手动编辑 desk 里的 `SOUL.md`。
+
+这次不是只删一个命令行参数，而是把围绕 persona 注入产生的整片产品面一起收回：参数解析、`SOUL.md` marker、persona 写回逻辑、对应测试、对应用户文档，都要一起删掉。
+
+一个硬边界必须写死：**已经存在的 assistant desk 不做迁移、不做批量改写、不静默触碰任何已有 `SOUL.md`。** 这次只优化中间层自己的内核与新建路径，不回写已经发出去给用户使用的办公桌资产。
+
+## 2. 背景
+
+之前为了降低 assistant 初次创建门槛，项目引入了 persona bootstrap：
+
+- `ally setup <name> --persona ...`
+- `ally setup <name> --persona-file ...`
+- `ally assistant add|ensure ...` 的同类参数
+
+对应实现不仅增加了参数入口，还在 `internal/modules/assistant/manage.sh` 里增加了一整套 persona 解析、marker 注入、局部覆盖写回逻辑，并同步扩散到 shell 测试、Quick Start、README、troubleshooting、manual acceptance。
+
+但产品方向现在已经变化：
+
+1. 桌面端已经具备直接编辑 `SOUL / NOW / MEMORY / MISTAKES` 的能力。
+2. 如果用户仍然走 CLI，通常说明他更偏程序员，可以直接编辑事实文件。
+3. 中间层当前的主目标是继续做薄，而不是为了“看起来方便”保留低价值包装层。
+
+因此，persona bootstrap 这条路径已经从“降低门槛”变成了“增加一层多余产品面”。
+
+## 3. 问题定义
+
+当前 persona bootstrap 继续存在，会带来 4 个问题：
+
+### 3.1 产品面比实际价值更厚
+
+这条能力并不是一个轻量参数，而是一整片产品合同：命令语义、文件注入、覆盖逻辑、错误处理、测试与文档都要维护。
+
+### 3.2 它让中间层替用户管理本应由资产层表达的内容
+
+人格本质上属于 assistant 的长期资产，应该落在 `SOUL.md`。当前中间层多做了一层“代填人格”，反而模糊了用户入口与资产入口的边界。
+
+### 3.3 它和当前主入口方向不一致
+
+既然桌面端已是普通用户默认入口，CLI 再保留一套 persona 引导，只会形成重复交互面。
+
+### 3.4 已有用户资产不能被静默重写
+
+一旦保留 `assistant ensure --persona` 这种路径，中间层就继续拥有修改已存在 `SOUL.md` 某个区域的权力。这和当前产品边界冲突，也不利于保护已发出去的 assistant desk 资产。
+
+## 4. 目标 / 非目标
+
+### 4.1 目标
+
+1. 删除 CLI persona 引导能力：`--persona`、`--persona-file` 不再是正式产品面。
+2. 删除 persona 注入相关实现代码，而不是只隐藏入口。
+3. 让新建 assistant 的默认 `SOUL.md` 回到简单、可手改的模板，不再依赖 marker 注入机制。
+4. 明确保证：不迁移、不修改任何已有 assistant 的 `SOUL.md`。
+5. 同步清理测试和当前态文档，避免产品说明继续漂移。
+
+### 4.2 非目标
+
+1. 不迁移历史 assistant desk。
+2. 不批量清洗旧 `SOUL.md` 中既有的“用户补充设定”区块或 marker。
+3. 不新增新的 CLI 替代入口，例如 `ally persona set`。
+4. 不改变桌面端直接编辑 `SOUL.md` 的能力。
+5. 不修改 assistant 现有记忆系统的其他文件职责。
+
+## 5. 产品定义与用户路径
+
+### 5.1 新的正式口径
+
+从这次变更之后，人设编辑只保留两条正式路径：
+
+- 桌面端直接编辑 `SOUL.md`
+- 用户自己手动编辑 assistant desk 中的 `SOUL.md`
+
+CLI 只负责创建与绑定 assistant，不再负责“顺手帮用户写一段人格”。
+
+### 5.2 用户路径
+
+#### 路径 A：普通用户
+
+1. 通过桌面端创建 assistant
+2. 需要调整人格时，在桌面端直接编辑 `SOUL.md`
+
+#### 路径 B：CLI / 程序员用户
+
+1. 执行 `ally setup <name> --workspace <path>`
+2. 如需补充人格，直接打开 desk 内的 `SOUL.md` 编辑
+
+#### 路径 C：已有 assistant
+
+- 现有 assistant 继续照常工作
+- 中间层不会因为本次升级去碰他们已有的 `SOUL.md`
+- 用户若未来要改人设，仍应自己在桌面端或文件里改
+
+## 6. 机制设计
+
+### 6.1 命令面收口
+
+以下参数从正式产品面移除：
+
+- `ally setup <name> --persona ...`
+- `ally setup <name> --persona-file ...`
+- `ally assistant add <name> --persona ...`
+- `ally assistant add <name> --persona-file ...`
+- `ally assistant ensure <name> --persona ...`
+- `ally assistant ensure <name> --persona-file ...`
+
+命令帮助、错误提示、文档示例都必须一起删除。
+
+### 6.2 `SOUL.md` 模板收口
+
+新的默认模板可以继续保留“用户补充设定”这一节，但它必须退回成普通静态 Markdown，而不是产品层可编程写回区域。
+
+也就是说：
+
+- 新模板里不再依赖 special marker
+- 中间层不再解析或覆盖该区域
+- 用户后续编辑完全交还给桌面端或手工文件编辑
+
+### 6.3 代码删除范围
+
+这次必须一起删除：
+
+1. persona 参数解析
+2. persona 文本归一化
+3. persona file 读取与互斥校验
+4. `SOUL.md` persona marker 常量
+5. persona block render / writeback / partial overwrite 逻辑
+6. 只为了 persona 注入而存在的测试样例与文档口径
+
+判断标准不是“入口没了”，而是“围绕 persona bootstrap 产生的中间层职责真的没了”。
+
+### 6.4 既有资产保护边界
+
+这是本 spec 最重要的机制约束：
+
+- 产品升级过程中，不扫 assistant desk，不迁移 `SOUL.md`
+- `ally assistant ensure` 不得因为 persona 能力下线而去重写已有 `SOUL.md`
+- 已存在 desk 中残留的 marker 或旧“用户补充设定”内容，视为用户现有资产的一部分，保持原样
+
+如果某个已有 assistant 的 `SOUL.md` 未来仍保留旧格式，那是允许的。中间层只需要确保以后不再继续依赖或改写它。
+
+### 6.5 测试与文档收口
+
+需要同步更新：
+
+- shell 测试：删除 persona 相关正向与报错路径
+- `README.md`
+- `docs/user-quickstart.md`
+- `docs/troubleshooting.md`
+- `docs/manual-acceptance.md`
+- 如有必要，更新 `PRODUCT.md` / `DASHBOARD.md`
+
+另外，旧的规划文档 `docs/planning/SPEC-assistant-persona-bootstrap.md` 不应继续保留成“Ready for implementation”的当前口径；应明确标注已被本 spec 取代。
+
+## 7. 验收标准
+
+1. CLI 帮助与参数解析中已不存在 `--persona` / `--persona-file`。
+2. 新建 assistant 时，`ally setup` 仍能正常创建 desk、配置与默认 `SOUL.md`。
+3. `ally assistant add` / `ally assistant ensure` 不再接受 persona 参数。
+4. `internal/modules/assistant/manage.sh` 中 persona 注入相关逻辑已删除，而不是仅闲置。
+5. persona 相关 shell 测试已删除或改写为新的默认模板断言。
+6. Quick Start / README / troubleshooting / manual acceptance 不再教用户使用 persona 参数。
+7. 现有 assistant desk 不会因升级或 `assistant ensure` 被静默改写 `SOUL.md`。
+8. 桌面端现有的 `SOUL.md` 直接编辑能力不受影响。
+
+## 8. 风险 / 假设 / 待决问题
+
+### 8.1 风险
+
+- 如果代码只删参数、不删写回逻辑，会留下死代码与未来误判点。
+- 如果默认模板改得过猛，可能影响新 assistant 的初始可读性。
+- 如果文档不一起改，用户会继续按旧说明使用，造成体验断裂。
+
+### 8.2 假设
+
+- 桌面端会继续作为普通用户的默认人设编辑入口。
+- CLI 用户可以接受直接手动编辑 `SOUL.md`。
+
+### 8.3 待决问题
+
+1. 默认 `SOUL.md` 是否继续保留“用户补充设定”这一节，还是进一步收成更中性的静态说明？
+   - 当前建议：保留，但只作为静态段落，不再做可编程注入。
+
+## 9. 实施建议
+
+建议按一个小步完成：
+
+1. 先删命令参数与写回逻辑
+2. 再简化模板
+3. 再删测试与同步文档
+4. 最后回归 `tests/shell/assistant.sh` 与相关 desk bootstrap 路径

package/docs/developer-workflow.md

@@ -0,0 +1,49 @@
+# 开发协作准则
+
+## 开发入口
+
+```bash
+cd work-ally
+export npm_config_cache=$PWD/.npm-cache
+npm install
+npm test
+```
+
+## 开发态与 install-first
+
+默认用户入口来自 npm 安装版本。
+
+开发建议：
+
+1. 在源码仓库开发、补测试
+2. 用 `WORK_ALLY_SOURCE_DIR=<repo>` 做源码联调
+3. 准备发布时执行：
+
+```bash
+npm run release:alpha
+```
+
+4. 在目标机器验证安装形态：
+
+```bash
+npm i -g work-ally@alpha
+ally status --assistant <name>
+```
+
+## 验证入口
+
+```bash
+npm test
+npm run runtime:health
+npm run runtime:probe -- 'Reply with exactly: OK'
+```
+
+## 文档同步要求
+
+行为变化后，同步更新：
+
+- `README.md`
+- `docs/user-quickstart.md`
+- `docs/manual-acceptance.md`
+- `docs/ops-runbook.md`
+- `docs/troubleshooting.md`