work-ally 0.2.0-alpha.1

package/docs/product-spec-standard.md

@@ -0,0 +1,528 @@
+# Product Spec Standard
+
+更新时间：2026-03-15  
+状态：Draft / Team standard proposal
+
+## 1. 这份标准解决什么问题
+
+这份标准不是为了把 spec 写得更长，而是为了让 spec 更稳定地起到三件事：
+
+1. 让产品经理把问题讲明白，而不是只给一个方向口号
+2. 让工程师在开工前知道边界、机制与验收，不靠猜
+3. 让评审者能快速判断：这件事是否真的 ready for implementation
+
+一份合格 spec 的目标不是“展示思考很多”，而是让后续协作的人能回答：
+
+- 这件事到底是什么
+- 为什么值得做 / 为什么现在做
+- 具体要怎么做，做到什么算完成
+
+## 1.1 第一性原理
+
+这份标准最终只服务一个目标：
+
+> **写出一份清晰、让别人看得懂、能据此正确开工的 spec。**
+
+因此，所有规则都要服从这三条原则：
+
+- 不为了显得专业而增加结构
+- 不为了省事而省掉关键机制
+- 不让后续协作者依赖作者本人现场解释
+
+如果一条规则不能明显提升“清晰、可理解、可开工”，它就不该进入团队标准。
+
+## 1.2 最小工作标准
+
+为了避免标准本身过重，团队日常执行只要求一份 spec 先满足下面 6 件事。
+
+### 必须讲清的 6 件事
+
+1. `是什么`
+   - 这次要做的 feature / 变化是什么
+2. `为什么`
+   - 解决什么真实问题，为什么现在做
+3. `范围`
+   - 这次做到什么，不做到什么
+4. `用户路径`
+   - 用户如何触发，主路径和关键异常路径是什么
+5. `机制`
+   - 对象、状态、流程、边界如何工作
+6. `完成标准`
+   - 什么叫 done，如何验证
+
+这 6 件事全部清楚，spec 才能进入 `Ready for implementation`。
+
+## 1.3 推荐分层
+
+为了兼顾“够用”和“不复杂”，建议把 spec 标准分成两层：
+
+- `最小标准`：所有非平凡需求都必须满足
+- `展开说明`：当 feature 更复杂时，再补更多细节
+
+在这个定义下：
+
+- 不是所有 spec 都必须写得很长
+- 但任何 spec 都不能跳过最小标准
+
+## 2. 什么时候必须写 spec
+
+满足任一条件，就应该先写 spec：
+
+- 改动会影响产品语义、默认行为或用户路径
+- 改动跨模块、跨角色或跨系统边界
+- 改动会引入新对象、新状态、新流程或新命令
+- 改动需要产品、工程、设计或运营共同理解同一件事
+- 改动一旦做错，后续返工成本明显高
+
+通常可不单独写 spec 的情况：
+
+- 纯文案微调
+- 局部、低风险 bugfix，且不改变产品语义
+- 已有 spec 覆盖范围内的实现细化
+
+## 3. 优秀 spec 的最低标准
+
+业界公开实践有几个稳定共识：
+
+- spec / PRD 不应 bloated；它首先要建立共享理解，而不是写成百科全书。Atlassian 明确强调有效 PRD 应该简洁，并至少包含目标、假设、设计和清晰的 out-of-scope。citeturn5view0turn5view1
+- spec 不只写“做什么”，还要写“为什么做、如何衡量成功”。Atlassian 对 product specification 的定义就是：说明 what、why，以及 success 如何衡量。citeturn5view1turn5view0
+- 好的产品文档要先把问题讲清楚，而不是直接接受表面方案。GitLab 明确要求 product 要追到 feature request 背后的基础问题，并先做 problem validation。citeturn5view2turn5view3
+- 文档写法应该直接、清楚、方便匆忙阅读的人理解；Google 的文档风格指南强调简单、一致、直白、避免长句和术语堆叠。citeturn5view5
+- 对中小团队来说，轻量但前置的 design/spec 文档比在代码评审里再吵架更有效。Microsoft Golazo 把 lightweight design doc 和 implementation 前 signoff 作为核心实践，并强调 concise design docs 会形成可检索的长期团队上下文。citeturn5view6
+
+结合这些实践，`work-ally` 需要的不是“大而全模板”，而是一套**够用、可审、能派工**的标准。
+
+## 4. 一份 spec 必须回答的 8 个问题
+
+如果一份 spec 不能清楚回答下面 8 个问题，就不算 ready：
+
+1. 这件事是什么？
+2. 为什么要做？不做会怎样？为什么现在做？
+3. 这次到底做到哪里，不做到哪里？
+4. 用户路径 / 使用场景是什么？
+5. 产品对象、状态、流程、边界如何变化？
+6. 关键机制是什么？系统如何工作？
+7. 什么叫完成？如何验证？
+8. 已知风险、假设和待决问题是什么？
+
+其中：
+
+- `是什么` = 产品定义、scope、对象
+- `为什么` = 背景、问题、目标、优先级理由
+- `如何做` = 机制、流程、状态机、接口边界、迁移、验收
+
+## 5. 推荐标准结构
+
+先说结论：
+
+- **团队执行以“最小结构”作为硬标准**
+- **更完整的 10 段结构，作为复杂 feature 的推荐展开版**
+
+### 5.1 最小结构（默认标准）
+
+对大多数 feature，先写到下面 7 段就够了：
+
+1. `Summary`
+2. `背景`
+3. `问题定义`
+4. `目标 / 非目标`
+5. `产品定义与用户路径`
+6. `机制设计`
+7. `验收标准 + 风险/假设/待决问题`
+
+如果这 7 段已经清楚，文档就可以很短，但仍然合格。
+
+### 5.2 完整结构（复杂 feature 推荐）
+
+建议默认使用下面 10 段结构。对小 feature 可以压缩，但不要跳过关键问题。
+
+### 5.3 Header
+
+至少包含：
+
+- 标题
+- 更新时间
+- 状态
+- 作者 / owner
+- 相关文档
+
+### 5.4 Summary
+
+用 3-6 句话讲清楚：
+
+- 这是什么 feature
+- 它解决什么问题
+- 这次交付的核心变化是什么
+
+要求：
+
+- PM、工程师、评审者只看这一段，也能大致知道文档值不值得继续读
+
+### 5.5 背景
+
+回答：现状是什么，为什么会走到今天。
+
+要写：
+
+- 当前行为 / 现有能力
+- 用户或业务上下文
+- 触发这次 spec 的事实基础
+
+不要写：
+
+- 过长迁移史
+- 与本次决策无关的历史八卦
+
+### 5.6 问题定义
+
+这是最重要的一段之一。
+
+要求：
+
+- 问题必须是“用户/产品/系统”的真实缺口，不是“我想做个功能”
+- 优先写问题，而不是先写方案
+- 尽量拆成 2-5 个子问题
+
+好问题定义通常包括：
+
+- 谁遇到问题
+- 在什么场景遇到
+- 具体卡在哪里
+- 造成什么后果
+- 当前为什么不能靠已有方案解决
+
+### 5.7 目标与非目标
+
+目标写“这次必须达成什么”；非目标写“这次明确不做什么”。
+
+要求：
+
+- 目标不要写成抽象愿景，要能判断是否达成
+- 非目标必须能防止 scope 失控
+
+### 5.8 产品定义与用户路径
+
+回答“是什么”。
+
+至少要包含：
+
+- feature 的一句话定义
+- 用户看到什么
+- 用户如何触发
+- 典型路径 A / B / C
+- 异常路径或拒绝路径
+
+如果是非 UI feature，也要写“谁通过什么入口触发，得到什么结果”。
+
+### 5.9 机制设计
+
+回答“如何做”，但不是写代码。
+
+这是很多 spec 最容易缺的部分。最少要讲清：
+
+- 新增或变化的核心对象
+- 关键字段 / 主键 / 关系模型
+- 状态机或状态切换条件
+- 端到端流程
+- 模块职责边界
+- 外部依赖和内部依赖
+- 迁移 / 兼容 / fallback 机制
+
+如果 feature 有下列任意一种，就必须单独写清：
+
+- 新对象
+- 新 ID
+- 新状态
+- 新命令
+- 新持久化结构
+- 新的“当前绑定 / 历史保留 / 默认行为”
+
+### 5.10 Scope / Phase
+
+如果事情不小，必须写 phase。
+
+要求：
+
+- Phase 要按产品可交付切，不按工程模块切
+- 每个 phase 都要说明交付了什么用户价值
+- V1 必须能独立成立，不能只是“铺底但用户无感”
+
+反例提醒：
+
+- 不要把 `前端页搭建 / 状态接口接入 / 本地存储改造 / 联调` 这类工程拆任务直接写成产品 phase
+- 不要把 phase 写成“先把基础设施铺好，用户暂时感知不到”的占位说法
+- 如果 phase 只能说明工程顺序，不能说明每一段用户会获得什么新价值，说明 phase 写法不合格
+
+### 5.11 验收标准
+
+这是 spec 是否可派工的硬门槛。
+
+至少要写：
+
+- 功能验收
+- 语义验收
+- 验证建议
+
+好的验收标准应该满足：
+
+- 工程师能据此写测试
+- 评审者能据此判断 done / not done
+- 不依赖作者本人现场解释
+
+### 5.12 风险 / 假设 / 待决问题
+
+必须区分三类：
+
+- `风险`：已知可能出问题，但可以先推进
+- `假设`：当前先按某个前提推进
+- `待决问题`：不拍板就会影响设计或排期
+
+不要把所有不确定性都扔进 open questions。
+
+## 6. 对“如何做”的最低要求
+
+产品经理不需要把 spec 写到程序员直接 copy 成代码，但至少要让工程师不再猜下面这些关键点：
+
+- 主要对象是什么
+- 哪个 ID 是主键
+- 当前 / 历史 / 活跃 / 关闭分别是什么意思
+- 默认路径是什么
+- 异常路径怎么处理
+- 谁负责更新状态
+- 什么信息要持久化
+- 什么时候需要迁移旧数据
+
+简单说：
+
+- 不要求代码级实现
+- 但要求机制级清晰
+
+一个实用判断方法：
+
+> 如果换一个没参与讨论的工程师来读，是否能画出流程图、状态图和模块拆分？
+
+如果不能，说明 spec 的“如何做”还没写清。
+
+## 6.1 什么情况下必须展开“机制设计”
+
+为了防止把每份 spec 都写成复杂设计文档，只在下面这些情况强制展开写：
+
+- 引入新对象
+- 引入新 ID / 主键
+- 引入新状态或状态切换
+- 引入新命令 / 新入口
+- 涉及 current / history / default / fallback 这类默认行为
+- 涉及持久化结构变化
+
+如果都不涉及，机制设计可以很短；如果涉及其中任意一项，就不能只写方向。
+
+## 7. 写作要求
+
+### 7.1 语言要求
+
+- 先结论，后展开
+- 句子短，少套话
+- 一个术语只表达一个意思
+- 少用“可能 / 也许 / 大概 / 之类”
+- 少写空话，比如“提升体验”“增强能力”而不解释具体提升什么
+
+### 7.2 术语要求
+
+- 新术语必须定义
+- 同一概念在全文只能有一个主叫法
+- 不要混用用户概念和系统概念
+
+例如：
+
+- `conversation` 是外部聊天窗口
+- `work session` 是产品级连续会话
+- `engine session` 是底层 runtime 可恢复会话
+
+如果三者混着写，工程实现一定会歪。
+
+### 7.3 篇幅要求
+
+- 小 feature：800-1800 字常常足够
+- 中等 feature：1500-3500 字更常见
+- 大 feature：可以更长，但必须靠结构让人可扫读
+
+长不是问题，**结构差和信息密度低才是问题**。
+
+## 8. `work-ally` 语境下的特别要求
+
+对这个仓库，spec 还要额外讲清楚下面几类边界：
+
+- 用户看到的产品概念，和系统内部 runtime / bridge 概念的区分
+- 项目工作现场、assistant desk、runtime 之间的边界
+- 默认行为是什么，用户是否需要显式命令
+- 哪些内部实现细节不能暴露给普通用户
+- 哪些改动会影响 README、quickstart、ops runbook、troubleshooting
+
+如果 spec 涉及以下变化，必须明确写“文档联动要求”：
+
+- 命令语义变化
+- desk 结构变化
+- 记忆机制变化
+- 审批机制变化
+- bridge 行为变化
+
+## 9. 评审通过线
+
+为了保持实用，评审不要追求“写满模板”，而只看一个问题：
+
+> 一个没参与前期讨论的工程师，是否能读完后正确开工？
+
+如果答案是否定的，就说明不是结构不够多，而是清晰度还不够。
+
+建议把 spec 评审分成两层：
+
+### 9.1 Ready for review
+
+满足：
+
+- 背景、问题、目标、非目标都有
+- 用户路径能讲清楚
+- 没有明显术语混乱
+
+### 9.2 Ready for implementation
+
+满足：
+
+- 对象、状态、流程、边界已清楚
+- 验收标准已可测试
+- 风险 / 假设 / 待决问题已分类
+- 关键 open question 不再阻塞工程拆解
+- 如果写了 `Scope / Phase`，其分段必须是按用户价值切的可交付阶段，而不是工程任务分解
+
+## 10. PM 自评分表
+
+每项 0-2 分：
+
+- `0` = 缺失或明显不清楚
+- `1` = 有，但仍需大量口头补充
+- `2` = 清楚、可评审、可派工
+
+### 10.1 快速版自检
+
+在正式打分前，先过这 4 个 yes/no 问题：
+
+1. 只看 summary，别人能知道这次改什么吗？
+2. 只看问题定义，别人能知道为什么非做不可吗？
+3. 只看机制设计，工程师能画出主流程吗？
+4. 只看验收标准，评审能判断 done / not done 吗？
+
+如果任一答案是 `否`，先不要进入打分。
+
+### 10.2 评分项
+
+1. Summary 是否在开头就讲清这件事是什么
+2. 背景是否交代清楚现状与触发原因
+3. 问题定义是否在讲真实问题，而不是先塞方案
+4. 目标与非目标是否明确且不打架
+5. 用户路径是否覆盖主路径和关键异常路径
+6. 产品对象 / 术语 / 主键是否清楚
+7. 状态机或关键状态切换是否清楚
+8. 端到端机制是否能让工程师画出流程图
+9. 验收标准是否足够判断 done / not done
+10. 风险 / 假设 / 待决问题是否分开写清楚
+
+### 10.3 通过标准
+
+- 总分至少 `16 / 20`
+- 第 3、6、8、9 项不能低于 `1`
+
+如果任一关键项为 `0`，不应标记为 Ready for implementation。
+
+## 11. 推荐模板
+
+### 11.1 最小模板
+
+下面这个版本适合作为团队默认模板：
+
+```md
+# SPEC: <title>
+
+更新时间：YYYY-MM-DD
+状态：Draft / Ready for review / Ready for implementation / In implementation / Shipped
+Owner：<name>
+
+## 1. Summary
+
+## 2. 背景
+
+## 3. 问题定义
+
+## 4. 目标 / 非目标
+
+## 5. 产品定义与用户路径
+
+## 6. 机制设计
+
+## 7. 验收标准
+
+## 8. 风险 / 假设 / 待决问题
+```
+
+### 11.2 完整模板
+
+下面这个模板足够覆盖大多数 feature：
+
+```md
+# SPEC: <title>
+
+更新时间：YYYY-MM-DD
+状态：Draft / Ready for review / Ready for implementation / In implementation / Shipped
+Owner：<name>
+相关文档：<links>
+
+## 1. Summary
+
+## 2. 背景
+
+## 3. 问题定义
+
+## 4. 目标
+
+## 5. 非目标
+
+## 6. 产品定义与用户路径
+
+## 7. 机制设计
+
+### 7.1 对象与关系
+
+### 7.2 状态机
+
+### 7.3 端到端流程
+
+### 7.4 模块边界 / 依赖 / 迁移
+
+## 8. Scope / Phase
+
+## 9. 验收标准
+
+## 10. 风险 / 假设 / 待决问题
+```
+
+## 12. 对当前仓库 spec 的观察
+
+当前仓库里比较稳定的优点是：
+
+- 多数 spec 已经有“背景 / 问题 / 目标 / 非目标 / 验收”这些骨架，例如 [SPEC-session-presence-and-state-visibility.md](/Users/allenfeng/Development/Repositories/work-ally/docs/planning/SPEC-session-presence-and-state-visibility.md) 和 [SPEC-runtime-connection-and-turn-recovery-semantics.md](/Users/allenfeng/Development/Repositories/work-ally/docs/planning/SPEC-runtime-connection-and-turn-recovery-semantics.md)。
+- 一些较强的 spec 已经开始讲 durable ledger、状态流转、实现要求，这说明团队已经天然在往“机制级 spec”走。
+
+当前更常见的缺口是：
+
+- `如何做` 仍然容易停留在方向，而没有把对象、ID、状态机、端到端流程讲透
+- 有时“用户概念”和“系统概念”会混写
+- 有时 phase 是按工程模块切，而不是按用户价值切
+
+这也是为什么下一阶段最值得统一的，不是“再加更多章节”，而是把“机制设计”这一段写扎实。
+
+## 13. 结论
+
+对 `work-ally` 来说，一份够用的优秀 spec 标准可以压缩成一句话：
+
+> **用最少但完整的结构，把“是什么、为什么、如何做、做到什么算完成”讲清楚，让一个没参与前期讨论的工程师也能正确开工。**
+
+如果做不到这一点，文档再长也不算好 spec。

package/docs/troubleshooting.md

@@ -0,0 +1,45 @@
+# 排障手册
+
+## 源码已经改了，但安装版 `ally` 还是旧行为
+
+先执行：
+
+```bash
+npm i -g work-ally@alpha
+```
+
+当前默认入口是 npm 安装形态，不是源码树。
+
+这意味着：
+
+- 你在源码仓库里改代码，不会自动影响已安装版本
+- 需要 npm 安装/升级后，默认 `ally` 才会更新
+- 如果你要直接联调源码，请显式带 `WORK_ALLY_SOURCE_DIR=<repo>`
+
+## `ally start` 失败
+
+优先按顺序排：
+
+1. `ally status --assistant <name>`
+2. `ally logs bridge --assistant <name>`
+3. `ally logs supervisor --assistant <name>`
+
+常见原因：
+
+- assistant 未 setup
+- Feishu 配置缺失或权限未开通
+- 在受限 AI 执行环境中拉起长期进程
+
+## 如何确认安装来源
+
+执行：
+
+```bash
+ally status --assistant <name>
+```
+
+重点看：
+
+- `install channel`
+- `implementation`
+- `install root`

package/docs/user-quickstart.md

@@ -0,0 +1,46 @@
+# 用户快速开始（CLI）
+
+## 前提
+
+- Node.js 与 npm 已安装
+- 首发正式支持平台：`macOS arm64`
+- 已有可用的模型 provider 环境变量
+
+## 安装
+
+```bash
+npm i -g work-ally@alpha
+```
+
+安装后确认：
+
+```bash
+ally help
+```
+
+## 三步启动
+
+```bash
+ally setup <assistant-name> --workspace /path/to/your-project
+ally start --assistant <assistant-name>
+ally status --assistant <assistant-name>
+```
+
+## 升级
+
+```bash
+npm update -g work-ally
+# 或固定 alpha 通道
+npm i -g work-ally@alpha
+```
+
+## 关键说明
+
+- 默认是 install-first：`ally` 行为来自当前 npm 安装版本
+- 如果你在源码仓库开发并想直接联调，可显式使用：
+
+```bash
+WORK_ALLY_SOURCE_DIR=/path/to/work-ally ally status --assistant <assistant-name>
+```
+
+- 当前不支持用户侧定时任务能力；默认不会在无触发时自行执行任务

package/internal/dispatch.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/lib/common.sh"
+
+usage() {
+  local cmd_name
+  cmd_name=$(work_ally_cmd_name)
+  cat <<EOF2
+Usage: $cmd_name <command> [args]
+
+Commands:
+  setup                                    # assistant scope; requires --workspace <path>
+  assistant <add|ensure|bind|remove|rename|list|show> [args]   # global profile management
+  start                                    # assistant scope; use --assistant <name> when needed
+  stop                                     # assistant scope; use --assistant <name> when needed
+  restart                                  # assistant scope; use --assistant <name> when needed
+  status                                   # assistant scope; use --assistant <name> when needed
+  logs [bridge|runtime|supervisor|routine] [follow|print|--tail N]   # assistant scope
+  update                                   # assistant scope
+  codex                                    # assistant scope; launch official Codex CLI with assistant profile
+  new|continue|attach|threads [args]       # assistant scope; managed Codex thread actions
+  handoff <codex|attach|new|continue|threads> [args]   # assistant scope; compatibility wrapper
+  mcp <status|install-feishu|remove-feishu|list>          # assistant scope
+  routine <list|run|enable|disable> [args]                # assistant scope
+  thread-sync [--thread <id>|--json]         # assistant scope; sync thread conversation snapshot(s)
+  global <list|stop> [args]                # machine scope; `global list` shows currently running assistants
+  help
+EOF2
+}
+
+CMD="${1:-help}"
+shift || true
+
+case "$CMD" in
+  help|-h|--help)
+    usage
+    ;;
+  assistant)
+    exec "$SCRIPT_DIR/modules/assistant/manage.sh" "$@"
+    ;;
+  global)
+    exec "$SCRIPT_DIR/modules/global/manage.sh" "$@"
+    ;;
+esac
+
+work_ally_init_context
+work_ally_ensure_state_dirs
+
+case "$CMD" in
+  setup)
+    exec "$SCRIPT_DIR/modules/bootstrap/setup.sh" "$@"
+    ;;
+  start)
+    exec "$SCRIPT_DIR/modules/runtime/start.sh" "$@"
+    ;;
+  stop)
+    exec "$SCRIPT_DIR/modules/runtime/stop.sh" "$@"
+    ;;
+  restart)
+    exec "$SCRIPT_DIR/modules/runtime/restart.sh" "$@"
+    ;;
+  status)
+    exec "$SCRIPT_DIR/modules/runtime/status.sh" "$@"
+    ;;
+  logs)
+    exec "$SCRIPT_DIR/modules/ops/logs.sh" "$@"
+    ;;
+  update)
+    exec "$SCRIPT_DIR/modules/runtime/update.sh" "$@"
+    ;;
+  mcp)
+    exec "$SCRIPT_DIR/modules/mcp/manage.sh" "$@"
+    ;;
+  codex)
+    exec "$SCRIPT_DIR/modules/handoff/manage.sh" "codex" "$@"
+    ;;
+  handoff)
+    exec "$SCRIPT_DIR/modules/handoff/manage.sh" "$@"
+    ;;
+  new|continue|attach|threads)
+    exec "$SCRIPT_DIR/modules/handoff/manage.sh" "$CMD" "$@"
+    ;;
+  routine)
+    exec "$SCRIPT_DIR/modules/routines/manage.sh" "$@"
+    ;;
+  thread-sync)
+    exec "$SCRIPT_DIR/modules/handoff/manage.sh" "thread-sync" "$@"
+    ;;
+  *)
+    work_ally_die "Unknown command: $CMD"
+    ;;
+esac