work-ally 0.2.0-alpha.1

package/docs/planning/assistant-workbench-spec.md

@@ -0,0 +1,725 @@
+# assistant-workbench-spec
+
+更新时间：2026-03-18
+状态：Historical / drifted
+
+> 说明：这份文档承载的是较早阶段的产品设想，已明显落后于当前 shipped model。
+> 当前 assistant desk、独立 `CODEX_HOME`、项目绑定、作用域命令与桌面控制面等主能力，请优先以 `README.md`、`DASHBOARD.md`、`docs/implementation/work-ally-implementation-guide.md` 为准。
+> 如需看当前会话主线，请改读 `docs/planning/SPEC-codex-same-machine-session-handoff.md`；不要再把本文当作可直接派工的现行 spec。
+
+本 spec 定义 `work-ally` 下一阶段的正式产品路线：**命名助理独立 profile + 当前项目自然叠加**。
+
+它面向实现者，而不是面向讨论过程本身。
+目标是让另一位工程师读完后，能够直接开始设计与开发，而不需要再回头猜测“我们到底想做什么”。
+
+---
+
+## 1. 文档目标
+
+这份文档要回答四个问题：
+
+1. 这个 feature 到底是什么
+2. 为什么要这样做
+3. 产品边界是什么
+4. 工程上应如何落地
+
+本 spec 只保留最终结论，不保留方案比较、发散路径或讨论痕迹。
+
+---
+
+## 2. 一句话定义
+
+> **给每个助理一个独立 profile，并在当前项目目录中用该 profile 启动 Codex；项目自身规则继续通过项目目录自然生效。**
+
+换句话说：
+
+- 助理是谁，放在助理 profile
+- 项目怎么工作，放在项目目录
+- `work-ally` 负责把这两层稳定叠加起来
+
+---
+
+## 3. 产品结论
+
+### 3.1 最终路线
+
+本 feature 的正式路线如下：
+
+- 每个命名助理拥有自己的独立 profile
+- profile 的技术承载方式是独立 `CODEX_HOME`
+- 用户总是在**当前项目目录**里启动助理
+- 当前项目自己的 `AGENTS.md` 按 Codex 原生机制自然生效
+- 助理级 guidance 通过该助理的 `CODEX_HOME` 注入
+
+### 3.2 不做的事
+
+本 feature **不**负责：
+
+- 不保证用户在原生 Codex App / CLI / IDE 中仍命中同一个助理身份
+- 不把项目变成助理工作台的一部分
+- 不引入 `assistant-root/project/` 作为核心模型
+- 不自建新的会话、上下文、thread、memory runtime
+- 不把长期记忆全文塞进 prompt
+- 不改写项目原有 `AGENTS.md` 作为默认实现路径
+
+### 3.3 产品承诺
+
+`work-ally` 只承诺下面这件事：
+
+> **当用户通过 `work-ally` 在某个项目目录中启动指定助理时，该助理的 profile 会被稳定注入，当前项目规则也会稳定生效。**
+
+除此之外，不做额外承诺。
+
+---
+
+## 4. 问题定义
+
+### 4.1 我们真正要解决的问题
+
+当前问题不是“如何让 Codex 在所有入口保持同一人格”，而是：
+
+> **如何让一个命名助理在通过 `work-ally` 启动时，具备稳定、可恢复、可复用的助理身份。**
+
+这个问题包含三层要求：
+
+1. 助理要有长期身份，而不是每次都靠临时 prompt 拼接
+2. 项目自身规则不能被助理层覆盖或污染
+3. 助理长期资产不能与项目仓库混在一起
+
+### 4.2 为什么不能把助理直接揉进项目里
+
+如果把助理人格、记忆、知识、工作流都直接塞进项目目录，会出现以下问题：
+
+- 人和项目混层：项目是工作对象，助理是工作主体
+- 项目迁移困难：同一个助理跨项目会不断重复初始化
+- 规则冲突：项目已有 `AGENTS.md` 时，助理规则与项目规则容易纠缠
+- 资产归属不清：长期记忆和项目代码会混进同一个边界
+- 恢复能力差：项目删了、迁了、拆了，助理身份也跟着丢
+
+因此，助理必须有独立于项目的身份容器。
+
+---
+
+## 5. 产品边界
+
+### 5.1 我们支持什么
+
+本 feature 支持：
+
+- 注册多个命名助理
+- 为每个助理维护独立 profile
+- 在任意项目目录中选择某个助理启动
+- 让助理级 guidance 与项目级 guidance 正常叠加
+- 让助理长期资产与项目资产分离
+
+### 5.2 我们刻意不支持什么
+
+本 feature 不支持：
+
+- “同一个助理跨所有 Codex 入口自动一致”
+- 一助理同时编排多个项目
+- 当前对话里动态切主项目并重新挂载新项目规则
+- 产品层实现自己的上下文压缩 / 总结 / 分层记忆系统
+- 助理人格通过修改用户项目文件来实现
+
+### 5.3 为什么不保证“所有入口同身份”
+
+这是刻意的产品边界，而不是缺陷。
+
+原因如下：
+
+- 原生 Codex 是原生 Codex
+- `work-ally` 是在原生 Codex 之上增加“命名助理模式”的产品层
+- 用户若绕过 `work-ally` 直接使用其他入口，属于另一种使用模式
+- 我们不会为了追求“所有入口统一人格”而引入额外复杂度和脆弱性
+
+因此，产品上明确区分：
+
+- **原生模式**：用户直接使用 Codex 自己的默认环境
+- **助理模式**：用户通过 `work-ally` 使用命名助理 profile
+
+---
+
+## 6. 核心概念
+
+### 6.1 Assistant
+
+`Assistant` 是一个可注册、可命名、可复用的助理身份。
+
+每个助理包含：
+
+- `name`：助理名
+- `assistant_home`：助理长期资产目录
+- `codex_home`：该助理专属 `CODEX_HOME`
+- `profile`：助理级 guidance 与 profile 配置
+
+它回答的是：
+
+- 这个助理是谁
+- 这个助理长期如何工作
+- 这个助理有哪些长期资产
+- 这个助理的入口 guidance 是什么
+
+### 6.2 Project
+
+`Project` 不是一个需要我们建模的新对象。
+
+`Project` 在本 feature 中只意味着：
+
+- 用户当前所在的工作目录
+- Codex 当前真正要读写和执行的目录
+- 项目规则、构建方式、测试方式的天然承载地
+
+本 feature 不引入额外 `project` 实体，不做项目注册中心。
+
+### 6.3 Assistant Profile
+
+`Assistant Profile` 是命名助理的最小可运行身份集合。
+
+profile 的技术载体就是该助理独立的 `CODEX_HOME`。
+
+其中需要承载：
+
+- 助理级 `AGENTS.md`
+- 助理级配置
+- 助理长期资产入口信息
+
+### 6.4 Runtime State
+
+运行态仍然只是运行态。
+
+例如：
+
+- `.work-ally/`
+- pid / health / lock / queue
+- bridge state
+- runtime state
+- logs / sessions / archive
+
+这些是可重建的过程数据，不是助理身份本体。
+
+---
+
+## 7. 设计原则
+
+### 7.1 一层只做一件事
+
+- 助理层只定义助理是谁
+- 项目层只定义项目如何工作
+- 运行层只负责把两者接起来
+
+### 7.2 尽量走 Codex 原生机制
+
+- 项目规则继续走项目目录中的 `AGENTS.md`
+- 助理规则通过 `CODEX_HOME` 注入
+- 不在产品层发明第二套 guidance 继承系统
+
+### 7.3 边界清晰优先于省一步初始化
+
+即使用户需要理解“助理 profile”这个概念，
+也不能把助理长期资产、项目代码、运行时状态混成一团。
+
+### 7.4 默认实现必须低侵入
+
+除非未来出现硬性证据证明不够用，
+否则不允许把“自动改写项目 `AGENTS.md`”作为主路径。
+
+---
+
+## 8. 数据模型
+
+### 8.1 助理注册表
+
+系统需要有一份助理注册表，记录可用助理。
+
+注册表包含以下字段：
+
+- `assistant_name`
+- `assistant_home`
+- `codex_home`
+- `description`
+- `created_at` / `updated_at`
+
+结构示例：
+
+```yaml
+assistants:
+  allen:
+    assistant_home: /path/to/assistants/allen
+    codex_home: /path/to/assistants/allen/.codex-home
+    description: Personal engineering assistant for Allen
+```
+
+这里的格式只是结构示例，最终文件格式由实现确定，但字段语义必须保持一致。
+
+### 8.2 助理长期资产目录
+
+每个助理有独立长期资产目录。
+
+当前 spec 不强制固定目录树，但要求具备下列逻辑分区：
+
+- `profile/` 或 `codex_home/`
+- `memory/`
+- `knowledge/`
+- `docs/`
+- `routines/`
+- `archive/` 或其他留档目录
+
+是否最终物理命名成这些目录，不是当前 spec 的关键。
+
+关键要求只有两个：
+
+1. 助理资产独立于项目仓库
+2. 助理资产能独立备份、独立恢复、独立迁移
+
+### 8.3 助理级 `AGENTS.md`
+
+助理 profile 中必须存在一份助理级 `AGENTS.md`，作为助理身份入口。
+
+它的职责是：
+
+- 定义助理人格
+- 定义长期工作原则
+- 给出长期记忆索引
+- 标明关键目录映射
+- 告诉系统“需要更多资料时去哪里找”
+
+它不应承担：
+
+- 长篇记忆正文
+- 具体项目构建命令
+- 某个项目独有规范
+
+### 8.4 项目级 `AGENTS.md`
+
+项目目录中的 `AGENTS.md` 继续由项目自己负责。
+
+它的职责是：
+
+- 定义项目内的开发、构建、测试、提交流程
+- 定义项目特有约束
+- 定义仓库结构、模块规则等
+
+它不应承担：
+
+- 助理人格
+- 助理长期记忆
+- 助理全局行为风格
+
+---
+
+## 9. 运行时行为
+
+### 9.1 启动前提
+
+用户已经：
+
+- 进入目标项目目录
+- 明确要使用哪个命名助理
+
+本 feature 不处理“进入项目后再切到另一个项目”的复杂流程。
+
+### 9.2 启动流程
+
+当用户在当前项目目录启动某个命名助理时，系统执行：
+
+1. 解析目标助理名
+2. 从助理注册表中找到对应条目
+3. 读取该助理的 `codex_home`
+4. 以**当前目录**作为工作目录启动 Codex 运行时
+5. 将 `CODEX_HOME` 指向该助理 profile
+6. 保持项目目录原有 guidance 发现链不变
+
+最终效果：
+
+- 助理级 guidance 从助理 profile 来
+- 项目级 guidance 从当前项目目录来
+- 二者在一次启动中共同生效
+
+### 9.3 运行中可见性
+
+系统需要明确告诉用户以下信息：
+
+- 当前使用的助理名
+- 当前工作目录
+- 当前是否处于“助理模式”
+- 当前使用的 profile / `CODEX_HOME` 来源
+
+这是产品层必须显性的内容，避免用户误解自己现在到底在什么模式下工作。
+
+### 9.4 停止与重启
+
+停止和重启只影响当前运行实例，不改变：
+
+- 助理注册信息
+- 助理长期资产
+- 项目目录本身
+
+也就是说，运行实例可销毁，但助理身份必须可恢复。
+
+---
+
+## 10. 配置、凭证与责任分层
+
+### 10.1 配置隔离原则
+
+本 feature 的正式配置策略如下：
+
+- 每个助理拥有独立 `CODEX_HOME`
+- 每个助理拥有自己的 `config.toml` 与本地状态目录
+- 助理的模型、推理强度、verbosity、MCP、审批策略等默认值，都在该助理自己的 profile 中定义
+- 助理之间不共享配置文件本体
+
+也就是说：
+
+> **助理的行为默认值按助理隔离。**
+
+### 10.2 凭证策略
+
+本 feature 的正式凭证策略如下：
+
+- 助理配置独立
+- 凭证默认共享
+
+当前实现采用：
+
+- 各助理自己的 `config.toml` 可以独立存在
+- 配置中的 provider 凭证引用共享环境变量或共享认证来源
+- 不要求用户为每个助理重复录入同一套 API key
+- 不应把同一份密钥复制散落到多个助理目录中作为默认做法
+
+也就是说：
+
+> **独立的是助理配置，不是默认要求独立的是助理密钥。**
+
+这样做的原因是：
+
+- 能保留每个助理的独立行为默认值
+- 能降低用户初始化成本
+- 能减少敏感凭证在多个目录中的散落
+- 同时保留未来按助理隔离凭证的扩展空间
+
+### 10.3 产品层责任
+
+`work-ally` 负责：
+
+- 助理注册与查找
+- 助理 profile 解析
+- 启动时注入正确 `CODEX_HOME`
+- 让当前项目目录继续作为工作目录
+- 在状态与日志中明确当前助理身份
+- 让每个助理拥有独立配置面
+- 让默认凭证来源保持共享且可复用
+
+### 10.4 Codex 原生责任
+
+Codex 原生负责：
+
+- 基于 `CODEX_HOME` 加载全局 guidance
+- 基于当前项目目录加载项目 guidance
+- 读取对应 profile 下的模型与运行配置
+- 在运行时管理 thread / context / compaction / tool use 等原生能力
+
+### 10.5 项目自身责任
+
+项目自己负责：
+
+- 维护项目级 `AGENTS.md`
+- 维护本项目测试、构建、提交流程
+- 维护项目代码与 Git 历史
+
+---
+
+## 11. 默认用户路径
+
+### 11.1 标准路径
+
+标准用户路径如下：
+
+1. 用户进入目标项目目录
+2. 用户选择一个已注册助理
+3. 用户通过 `work-ally` 启动该助理
+4. 系统以当前项目目录 + 该助理 profile 启动 Codex
+5. 用户开始对话、修改代码、调用工具
+
+### 11.2 非标准路径
+
+如果用户绕过 `work-ally`，直接使用原生 Codex：
+
+- 可以正常工作
+- 但不属于本 feature 保证范围
+- 不应假定仍命中同一个命名助理身份
+
+实现与文档中都必须明确这一点。
+
+---
+
+## 12. 失败场景与预期行为
+
+### 12.1 助理未注册
+
+若用户指定的助理不存在：
+
+- 启动失败
+- 提示助理未注册
+- 给出后续动作，例如注册或列出可用助理
+
+### 12.2 助理 profile 缺失或损坏
+
+若注册表存在，但 `codex_home` 不存在或关键文件缺失：
+
+- 启动失败
+- 报告 profile 不完整
+- 不得静默回退到用户默认 `~/.codex`
+
+### 12.3 项目目录无 `AGENTS.md`
+
+这是正常场景。
+
+预期行为：
+
+- 继续启动
+- 仅加载助理级 guidance
+- 不把“项目缺失 `AGENTS.md`”视为错误
+
+### 12.4 用户直接使用原生 Codex 后又回来用 `work-ally`
+
+这是正常场景。
+
+预期行为：
+
+- `work-ally` 重新按命名助理模式启动
+- 不尝试追踪外部运行实例的人格一致性
+- 只保证本次通过 `work-ally` 启动的实例是正确的
+
+---
+
+## 13. 实现约束
+
+### 13.1 不允许的实现捷径
+
+以下方式不得作为主实现：
+
+- 自动 prepend / overwrite 用户项目 `AGENTS.md`
+- 通过复制项目到助理目录来实现 profile 注入
+- 通过生成超长系统 prompt 代替助理级 `AGENTS.md`
+- 通过共享单一 `CODEX_HOME` + 临时文件覆盖的方式伪装多助理
+
+### 13.2 可接受的实现方向
+
+实现可以自由选择具体文件布局，但必须满足：
+
+- 每个助理有独立 `CODEX_HOME`
+- 当前项目目录保持原位，不被搬运、不被挂载为核心模型
+- 助理级 guidance 与项目级 guidance 是叠加关系，不是替代关系
+- 助理身份的建立不依赖修改项目仓库文件
+
+---
+
+## 14. 验收标准
+
+### 14.1 功能验收
+
+以下场景必须成立：
+
+1. 可以注册两个不同助理
+2. 同一项目目录中，使用不同助理启动时，能命中不同 profile
+3. 同一助理可在两个不同项目目录中启动
+4. 项目目录中的 `AGENTS.md` 仍按原有方式生效
+5. 项目目录没有 `AGENTS.md` 时仍可正常启动
+6. 助理 profile 缺失时启动明确失败，不静默回退
+
+### 14.2 产品验收
+
+系统需要让用户明确看到：
+
+- 当前助理是谁
+- 当前工作目录是什么
+- 当前正在使用助理模式，而非原生模式
+
+### 14.3 架构验收
+
+实现完成后，必须满足：
+
+- 助理资产与项目仓库边界清晰
+- 不需要修改项目 `AGENTS.md` 才能工作
+- 不引入新的上下文系统
+- 不引入 `assistant-root/project/` 作为产品核心
+
+---
+
+## 15. 后续阶段不在本次范围内的潜在扩展
+
+以下内容不在本次范围内：
+
+- 项目默认绑定某个助理
+- 助理共享 / 导出 / 团队分发
+- 助理市场或模板化初始化
+- 助理多项目调度
+- 可视化的助理列表与状态面板
+- 助理级长期记忆治理策略
+- 按助理隔离凭证与计费账户
+
+这些内容不阻塞当前正式路线落地。
+
+---
+
+## 16. 实施拆分
+
+本节将 spec 直接拆成可执行子任务，供下一位工程师按顺序推进。
+
+### 16.1 Task 1：定义助理注册表
+
+目标：建立“命名助理 -> profile / `CODEX_HOME` / 资产目录”的稳定映射。
+
+完成标准：
+
+- 能落地一份助理注册表
+- 能唯一定位某个助理的 `assistant_home`
+- 能唯一定位某个助理的 `codex_home`
+- 能判断助理是否已注册
+- 注册表字段语义与本 spec 一致
+
+当前状态：未开始
+
+### 16.2 Task 2：定义助理 profile 目录约定
+
+目标：确定每个助理 profile 与长期资产的最小目录结构。
+
+完成标准：
+
+- 明确助理级 `AGENTS.md` 放置位置
+- 明确 `config.toml` 放置位置
+- 明确长期资产目录的逻辑分区
+- 明确哪些内容属于 profile，哪些内容属于运行时状态
+
+当前状态：未开始
+
+### 16.3 Task 3：实现启动时的 `CODEX_HOME` 注入
+
+目标：在当前项目目录启动命名助理时，正确注入对应 profile。
+
+完成标准：
+
+- 启动时能根据助理名解析到 `codex_home`
+- Codex 运行实例使用该助理自己的 `CODEX_HOME`
+- 当前工作目录保持为用户所在项目目录
+- 项目级 `AGENTS.md` 仍能自然生效
+
+当前状态：未开始
+
+### 16.4 Task 4：实现配置与凭证策略
+
+目标：落地“配置独立、凭证默认共享”的正式结论。
+
+完成标准：
+
+- 每个助理拥有自己的 `config.toml`
+- 助理配置之间彼此独立
+- 默认 provider 凭证来自共享环境变量或共享认证来源
+- 不要求用户为每个助理重复录入同一套 API key
+- 不把同一份密钥复制散落到多个助理目录中作为默认行为
+
+当前状态：未开始
+
+### 16.5 Task 5：实现状态可见性
+
+目标：让用户清楚知道当前是谁、在哪、以什么模式运行。
+
+完成标准：
+
+- 状态输出中能看到当前助理名
+- 状态输出中能看到当前工作目录
+- 状态输出中能看到当前处于助理模式
+- 状态输出中能看到当前 profile / `CODEX_HOME` 来源
+
+当前状态：未开始
+
+### 16.6 Task 6：实现失败场景处理
+
+目标：让所有关键失败都具备一致、明确、不可误解的行为。
+
+完成标准：
+
+- 助理未注册时明确失败
+- `codex_home` 缺失或损坏时明确失败
+- 不发生静默回退到默认 `~/.codex`
+- 项目无 `AGENTS.md` 时仍可正常启动
+
+当前状态：未开始
+
+### 16.7 Task 7：补齐验证与文档
+
+目标：让该 feature 可验收、可交接、可继续开发。
+
+完成标准：
+
+- 有对应的最小验证路径
+- README 或相关维护文档补到位
+- 行为与本 spec 保持一致
+- 验收项能被逐条核对
+
+当前状态：未开始
+
+---
+
+## 17. 当前进度
+
+截至本 spec 更新时：
+
+- 产品路线：已拍板
+- 关键边界：已拍板
+- 配置与凭证策略：已拍板
+- 实现：未开始
+- 验收：未开始
+
+也就是说：
+
+> **这份文档当前承担的是“实现起点”职责，而不是“实施中记录”职责。**
+
+如果后续进入开发阶段，应由实施文档或任务文档承接实时进度，而不是回头污染本 spec 主体。
+
+---
+
+## 18. Definition of Done
+
+当且仅当满足以下条件时，本 feature 才算完成：
+
+### 18.1 Spec 层 DoD
+
+- 另一位工程师在低上下文下读完本文，知道要做什么
+- 另一位工程师在低上下文下读完本文，知道不该做什么
+- 另一位工程师在低上下文下读完本文，知道要从哪些子任务开始做
+
+### 18.2 实现层 DoD
+
+- 命名助理可被注册并解析
+- 不同助理可命中不同 `CODEX_HOME`
+- 同一助理可在不同项目目录启动
+- 项目级 `AGENTS.md` 与助理级 profile 能正确叠加
+- 配置独立、凭证默认共享的策略真实落地
+- 启动失败不发生静默回退到默认全局配置
+
+### 18.3 产品层 DoD
+
+- 用户能明确知道当前使用的是哪个助理
+- 用户能明确知道当前所在的工作目录
+- 用户能明确知道当前处于助理模式，而不是原生模式
+- 用户在关键错误场景下能得到明确、可操作的提示
+
+### 18.4 架构层 DoD
+
+- 不引入 `assistant-root/project/` 作为核心模型
+- 不修改项目 `AGENTS.md` 作为主实现路径
+- 不引入新的 thread / session / context 管理层
+- 助理资产、项目资产、运行时状态边界清晰
+
+---
+
+## 19. 最终结论
+
+本 feature 的正式定义如下：
+
+> `work-ally` 为命名助理提供独立 profile，并在当前项目目录中以该 profile 启动 Codex；项目规则继续由项目目录自然提供，助理身份与项目边界保持分离。
+
+这就是本 feature 的唯一主路线。