work-ally 0.2.0-alpha.1

package/AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS.md
+
+## 文件定位
+
+这个文件服务于 `work-ally` 产品线的工程维护者、未来的产品经理与协作者，不是给普通终端用户看的使用说明。
+
+`README.md` 是给工程维护者看的产品总览与入口地图；`DASHBOARD.md` 是产品负责人 / 项目负责人的轻量工作台；`docs/user-quickstart.md` 面向当前正式 CLI 用户；`docs/user-quickstart-desktop.md` 面向桌面端内测；本文件约束产品研发与维护口径。
+
+## 产品定位
+
+`work-ally` 是一个独立产品仓库：把**项目工作现场**连接到**命名 assistant 办公桌**与**官方 Codex runtime**。
+
+核心边界：**不要再造一个脑子。**
+
+- 项目目录是工作现场，不是 assistant 的家。
+- assistant 的身份、人格、记忆、对话资产属于 assistant desk。
+- 项目规则来自项目自身的 `AGENTS.md`。
+- `work-ally` 负责编排、桥接、生命周期与可观测性。
+
+## 稳定产品原则
+
+- 一个运行中的 ally 进程，对应一个 assistant desk。
+- 中间层默认遵守 KISS：保持小而美，只补项目协作真正存在的缝隙。
+- 官方 Codex / App Server 已稳定提供的能力默认直接复用，不在中间层重做一套。
+- 不为了"看起来完整"而把中间层做厚；尤其避免重复发明上下文压缩、第二套会话脑或镜像状态机。
+- 默认假设：一个 assistant 长期专注一个项目，不对外鼓励一助理多项目轮转。
+- 对用户暴露的配置越少越好；能内部拍板的不要外抛。
+- 记忆系统、assistant desk 结构、审批与桥接行为优先保持可读、可审计、可版本化。
+- 原材料与用户长期资产优先使用文件系统表达，不引入额外黑盒存储。
+- 新增 capability 默认先过 `skill-first` 判断：能作为 Skill 包成立的，不优先长进 `bridge/` 或 `internal/`。
+- `work-ally` 核心只守桥接合同；机制性 workflow 优先放进 `skills/`，用 `SKILL.md + scripts/references/assets` 表达。
+- 基础纪律、长期产品边界、表达与协作铁律继续留在规则层，不要误塞进 Skill。
+- Skill 只承接阶段性、按需触发、可复用的 workflow；如果一条规则必须始终生效，它就不属于 Skill。
+
+## 用户体验约束
+
+- 唯一用户入口是 `./ally.sh <command>`。
+- 不新增平行的用户入口脚本，除非明确决策变更。
+- 默认体验优先于“可配置性炫技”。
+- README 要能让后续维护者快速找到入口模块、状态目录、验证路径与相关文档，不记录迁移史。
+- `docs/user-quickstart.md` 必须能支撑当前正式 CLI 路径从零走通完整流程。
+
+## 仓库结构约束
+
+- `ally.sh`：用户入口 facade，仅做薄转发。
+- `internal/`：本地 bootstrap、desk 管理、配置生成、生命周期控制。
+- `bridge/`：bridge 核心、会话流转、审批、消息翻译、渠道适配。
+- `runtime/`：只包装官方 Codex runtime host，不在这里堆产品逻辑。
+- `skills/`：产品级 Skill 包与机制性 workflow；不承载主身份，只承载按需能力。
+- `docs/completed/`：已完成专题、已落地 spec、已收口 feature 账本。
+- `docs/planning/`：产品设计、feature spec、长期规划与待确认专题。
+- `tests/`：shell、unit、integration 验证。
+
+## 研发纪律
+
+- 优先修根因，不打兼容补丁，除非明确要求。
+- 方向变了就顺手清理废弃路径、旧文案和无效结构，保持架构干净。
+- 当命令语义、desk 结构、记忆机制、审批机制、桥接行为变化时，同步更新 README 与相关文档。
+- 新 feature 先补最小可验证测试，再扩大验证面。
+- 只要改动触及 `resume / restart / continuity / recovery`，至少补一条“重启后再发普通消息”的回归；不能只验证进程重启成功、`/codex`、`/new` 或其他控制命令表面正常。
+- runtime fallback / recovery 类问题做单测时，必须覆盖真实错误对象形态；不要只用理想化 mock 裸对象，避免测试绿而真实运行失败。
+- 面向用户的文案要短、准、直接，避免堆工程内部概念。
+- 实现代码文件超过 `300` 行时，必须先反思是否应拆分模块，而不是继续往里堆逻辑。
+- 新增或重构后的实现代码文件，原则上不应超过 `600` 行；若必须超过，需能在 spec 或实现说明中说清理由。
+- 达到 `1000+` 行的实现代码文件视为明确重构信号，不是常态；`1700 ~ 2000` 行级别文件不得继续膨胀，必须优先拆分收口。
+- 模块拆分应按职责和边界进行，不做单纯按行数切文件的机械拆分。
+
+## Spec 纪律
+
+- 只要是非平凡的产品需求、行为变更、架构调整或跨模块 feature，必须先给出一份可执行 spec，再进入实现。
+- 在本仓库里，`非平凡需求` 指满足任一条件的工作：会改变产品语义、默认行为或用户路径；会引入新对象、新状态、新流程或新命令；会跨模块、跨角色、跨系统边界；会影响长期维护口径；做错后返工成本明显高。
+- 这份 spec 的团队标准以 [docs/product-spec-standard.md](/Users/allenfeng/Development/Repositories/work-ally/docs/product-spec-standard.md) 为准。
+- spec 的最低要求不是“写得长”，而是让没参与前期讨论的技术人员读完后也能正确开工，而不是还要猜“为什么做、做到哪里、什么算完成”。
+- spec 至少要讲清：是什么、为什么、范围、用户路径、机制设计、验收标准，以及风险 / 假设 / 待决问题。
+- 产品要求如果只停留在口头想法、模糊方向或一句话诉求，默认不视为可开工输入；应先沉淀成项目级 spec。
+- 小修小补、纯文案调整、低风险 bugfix 可不单独立 spec；但只要改动会影响产品语义、默认行为、模块边界或长期维护口径，就应补 spec。
+- spec 属于项目资产，应沉淀在仓库内；未落地或待确认的通常放在 `docs/planning/`，已收口专题应进入 `docs/completed/`，若已进入明确实施阶段，可在 `docs/implementation/` 补充实施拆解与阶段 DoD。
+- 工程实现应优先对齐 spec；若实现过程中发现 spec 不成立或边界变化，不要静默偏航，应先回写 spec 再继续推进。
+- 新增 capability 的 spec，默认要显式回答一次：为什么它不是 Skill，或者为什么它应被定义为 `Core / Hybrid / Skill` 中的哪一类。
+- 当任务是起草、补齐、评审或自评分产品 spec 时，优先使用 [skills/product-spec/SKILL.md](/Users/allenfeng/Development/Repositories/work-ally/skills/product-spec/SKILL.md)。
+
+## 记忆与办公桌边界
+
+- 项目知识属于项目自己；assistant desk 只持有 assistant 自己的身份、记忆、对话与运行资产。
+- `SOUL.md`、`NOW.md`、`MEMORY.md`、`MISTAKES.md`、`journal/`、`conversations/` 是用户可见长期资产。
+- assistant desk 的默认本地自治边界是 desk 根目录，而不只是 `.system/`；维护 `SOUL.md`、`NOW.md`、`MEMORY.md`、`MISTAKES.md`、`journal/`、`conversations/` 等长期资产不应被产品层误判成越界操作。
+- `.system/archive/` 是稳定原材料层；`.system/runtime/`、`.system/logs/`、`.system/cache/`、`.system/runs/`、`.system/codex-home/` 属于实现层内部资产。
+- 进入 desk Git 的必须是应被回滚和审计的长期资产；运行期脏文件不得进入版本库。
+
+## 文档与产品判断口径
+
+- 项目级设计、规划、实施说明与 onboarding 文档都沉淀在仓库内，不写入 assistant desk。
+- 文档入口以 `README.md` 为准；产品负责人 / 项目负责人日常总览优先看根目录 `DASHBOARD.md`；产品同事入场优先看 `docs/product-onboarding.md`。
+- 看设计文档时先区分 `docs/architecture/`、`docs/implementation/`、`docs/completed/`、`docs/planning/` 四层职责，不要混读成同一类文档。
+- 历史文档若与现状冲突，优先以 `README.md`、本文件，以及相关文档开头声明的 shipped model 为准。
+- 做产品判断时，先区分用户问题、系统根因和产品边界，再讨论实现方案。
+- 默认要求中间层吃掉复杂性，不把端口、运行态细节、桥接实现等内部概念暴露给用户。
+
+## 验证基线
+
+发生 shell 或生命周期改动时，至少验证：
+
+- `bash -n ally.sh`
+- 相关 `internal/` shell 脚本语法
+- 最小可用的 `tests/shell/assistant.sh`
+- 必要时补 bridge 的 unit / integration 测试
+- 若改动涉及 bridge 会话恢复语义，还必须验证一次“已有 session 在重启后收到普通消息仍可继续处理”的自动化路径或明确的人工闭环
+- smoke `./ally.sh help`
+
+如果环境限制导致某项无法验证，交付时必须明确写出缺口。

package/DASHBOARD.md

@@ -0,0 +1,160 @@
+# Dashboard
+
+更新时间：2026-03-22
+维护人：Ally
+定位：产品负责人 / 项目负责人的轻量驾驶舱，不替代 `PRODUCT.md`、`README.md` 或各专题 SPEC。
+
+## 1. 怎么用
+
+这份文档只做 5 件事：
+
+1. 一眼看清当前产品现状
+2. 一眼看清哪些主线正在推进
+3. 一眼看清哪些事项已准备好、可派工认领
+4. 一眼看清还有哪些想法仍在整理
+5. 保留已完成事项的简短账本，方便回顾但不挤占主视野
+
+使用纪律：
+
+- `PRODUCT.md` 负责长期总纲，不写高频变动状态
+- `README.md` 负责当前 shipped model 与工程入口，不写产品排期看板
+- `TASK.md` 负责某一条正在施工的工程专题
+- `DASHBOARD.md` 负责项目级总览、主线状态与待认领队列
+
+## 2. 当前现状
+
+当前 `work-ally` 已进入“v1 主闭环已成立，开始继续产品化”的阶段。
+
+已成立的稳定基线：
+
+- assistant desk / 独立 `CODEX_HOME` / 项目绑定 / 作用域命令
+- Feishu 私聊主闭环、群聊最小显式触发、reply context、sender identity
+- official Codex runtime 接入、thread 续聊、`/new`、审批、停止、恢复
+- same-machine handoff 主合同
+- archive raw layer、conversation view layer、nightly memory digest
+- 审批自治边界、会话降噪与忙时输入门控、中间层异常透明化
+
+当前一句话判断：
+
+> 产品已经不是“从 0 到 1”，而是“有稳定主链路后，继续收口边界、降低门槛、补齐长期协作能力”。
+
+## 3. 进行中
+
+这些是当前已经进入施工、但尚未进入“等验收”阶段的主线。
+
+当前暂无需要继续施工的大型 bridge-core 或桌面包装入口主线。
+
+- 当前优先：继续收口 memory / archive 合同
+- 当前要求：后续 bridge 改动应继续遵守本轮已收口的薄边界，不再回长厚状态
+
+## 4. 待开发
+
+说明：当前已开工的事项不应同时留在本节。
+
+这些事项已经具备明确方向，适合后续派工或由程序员认领。
+
+认领规则：
+
+- 只有进入本节的事项，才视为“可派工 / 可认领”
+- 认领后，应补对应 spec / implementation doc / `TASK.md`，并把状态移入“进行中”
+- 未进入本节的想法，不应直接让程序员开工
+
+### A. memory system 合同收口
+
+- 状态：`Ready to refine`
+- 主输入：`docs/planning/FEATURE-memory-system.md`
+- 当前重点：注入合同、纠错合同、删除/更正语义、文件职责边界
+
+### B. stable archive contract 收口
+
+- 状态：`Ready to cleanup`
+- 主输入：`docs/planning/SPEC-stable-archive-contract.md`
+- 当前重点：把已落地主结构和真正稳定字段合同核对清楚
+
+## 5. 待验收
+
+这些事项不是待开发，而是已经部分完成或已完成实现，当前缺最后一段产品验收或真实使用确认。
+
+### A. Assistant rename
+
+- 状态：`Ready for acceptance`
+- 主文档：`docs/planning/SPEC-assistant-rename.md`
+- 当前情况：CLI `assistant rename <old> <new>`、主迁移路径、关键拒绝路径、README / QuickStart、shell tests 已落地并完成 clean-env 自测
+- 当前缺口：还差你这边最后一轮产品验收与真实使用确认
+
+### B. Feishu `merge_forward` 转发聊天提取
+
+- 状态：`Waiting for real Feishu acceptance`
+- 当前情况：自动化已覆盖正文提取与“这是转发聊天”语义带入
+- 当前缺口：还差一次真人 Feishu 验收，确认真实转发消息路径表现符合预期
+- 验收完成后：若结果正常，可从“部分落地”提升为已收口
+
+## 6. 规划中
+
+这些方向有明确价值，但还不适合直接进入施工。
+
+### A. Skill-first 能力包边界
+
+- 状态：`Ready to refine`
+- 主输入：`docs/planning/SPEC-skill-first-capability-packaging.md`
+- 当前判断：旧能力外迁先 hold；但后续新增 capability 默认先走 `skill-first` 判断，不再无边界长进中间层
+
+### B. 会话恢复与状态合同进一步收口
+
+- 主输入：`docs/planning/SPEC-runtime-connection-and-turn-recovery-semantics.md`
+- 当前角色：为异常、恢复、迟到结果、状态真相提供进一步产品收口
+
+### C. mode / reasoning depth
+
+- 当前判断：值得做，但要后置于定时任务、会话接续、memory 合同之后
+
+### D. reviewer / 汇报与把关
+
+- 当前判断：属于第二层增强，不抢当前主线顺位
+
+### E. 对外定时任务产品化
+
+- 当前判断：先冻结，不进入近期主线
+- 保留范围：只保留 `nightly memory digest` 这类产品内核级后台例行任务
+- 暂不推进：面向普通用户的自然语言注册、定时派工、定时回送与相关交互面
+
+## 7. 想法池
+
+这些是用户会经常抛出的想法，先留在这里，不直接等于待开发。
+
+- 对外技术客服型助理 / case-thread 协作模型
+- reaction shortcuts 作为语义输入
+- 更轻的产品负责人日常工作台与验收流
+
+规则：
+
+- 想法池里的内容，只有在问题定义、边界、验收标准收清后，才允许进入“待开发”
+- 没立 spec 的，不视为可直接派工输入
+
+## 8. 已完成
+
+这里只保留高价值已完成项，不写流水账。
+
+- assistant desk / 独立 `CODEX_HOME` / 项目绑定 / 作用域命令
+- Feishu 私聊主闭环与群聊最小显式触发
+- 项目群的强制 @ 单助理路由：已通过真人 Feishu 验收；同一 assistant 的私聊与群聊已确认进入独立 thread，并能正确回投到原 Feishu 会话
+- Markdown-rich 回复、reply context、group sender identity
+- 内核级 routine / scheduler / nightly memory digest
+- 会话降噪与忙时输入门控
+- 审批自治边界 / 自测默认授权
+- 审批快捷回复与批量审批收口
+- 中间层异常透明化
+- same-machine handoff：已通过产品验收；真实 Codex runtime smoke 仍受当前环境网络请求失败影响，暂不记为“真实链路全绿”
+- 极简桥梁语义与前台可见面收口：已完成实现、验证、文档回写与代码提交
+- Active turn 默认 steer / context compaction 可见性：已完成实现与测试；默认 follow-up 继续走 `turn/steer`，并在观测到 compaction 时只提示一次轻量系统消息
+- 忠实中间层核心瘦身重构 V2：已完成；普通自然语言主路径已彻底切掉 work-session ownership / attached session 依赖，`SessionMeta` / `TurnLedgerRecord` / `/status` surface 已删去一批厚状态字段，turn failure 路径也已单独收口，当前 `npm run test:bridge` 全绿
+- CLI persona bootstrap 已删除：`ally setup` / `assistant add|ensure` 不再接受 `--persona` / `--persona-file`；人格编辑正式收口到手工编辑 `SOUL.md`
+- 产品入口已收口为 CLI-only；桌面端线路已退场。
+- 工程 SOP Skill 化：第一批工程维护 Skills 已落地，当前仓库内已有 `issue-to-spec-triage`、`post-implementation-closure`、`feishu-production-debug` 三个内部 Skill；基础纪律继续留在规则层
+
+## 9. 当前提醒
+
+- 不再维护厚重 workbench；以后以这份 dashboard 作为轻量总览入口
+- 新增 capability 若可做成 Skill 包，默认不要先改 bridge core；先判断它是不是更适合外挂能力
+- 任何已开工专题，都必须同步状态到这里，避免“人已经在做，文档还写 Ready to start”
+- 任何准备派工的事项，都应先进入“待开发”，而不是散落在聊天记录里

package/PRODUCT.md

@@ -0,0 +1,113 @@
+# work-ally
+
+`work-ally` 是一个把**项目工作现场**连接到**官方 Codex 能力**的协作中间层。
+
+它的目标不是再造一个 AI 平台，而是解决真实项目里反复出现的协作断点：
+你在电脑前能高效推进，离开工位就断线；角色很多，但上下文散；执行能力很强，但项目推进仍然靠人肉转述和手工追状态。
+
+## 我们最初要解决的痛点
+
+如果只看模型能力，今天的问题已经不是“AI 会不会写代码”。
+真正卡住项目推进的，通常是下面这几件事：
+
+1. 工作入口割裂：电脑前一套、移动端一套，切换场景就要重讲上下文。
+2. 角色协作割裂：产品、开发、review 的对话和产物分散在不同窗口，责任链不连续。
+3. 资产归属割裂：项目知识、助理记忆、运行状态混在一起，长期维护越来越混乱。
+4. 执行与治理割裂：审批、恢复、回送、留痕都存在，但缺少统一协作层把它们稳稳接起来。
+
+`work-ally` 的意义在这里：
+它不是增加一个聊天入口，而是把“项目如何持续推进”这件事，从临时会话提升为可持续的工作系统。
+
+## 我们的核心判断
+
+我们坚持三个判断，不在这里妥协：
+
+- 项目目录是工作现场，不是助理的家。
+- 官方 Codex 是执行内核，我们不再造第二个脑子。
+- 中间层只补协作缝隙，不制造新的复杂系统。
+
+这也是为什么 `work-ally` 的边界一直在收紧：
+桥接、最小编排、审批与 user-input gate、结果回送、必要补偿；仅此而已。
+
+## 为什么基于 Codex，而不是自建或拼装另一套 Agent 内核
+
+这个选择不是品牌偏好，而是工程判断：业界公开评测已经反复说明，Agent 的工程效果不仅由底层模型决定，也强烈受执行 harness、工具调用协议和交互机制影响；例如 SWE-bench Verified 明确区分了统一最小 loop（bash-only）与完整系统榜单，EVMbench 也展示了同一模型在不同 harness 下表现会变化。对 `work-ally` 来说，我们需要的是稳定的工程执行协议（thread/turn/item、审批暂停与恢复）和长期可维护的薄中间层边界，而 Codex App Server 正好提供了这套能力，所以我们选择“复用已验证内核 + 保持桥接层克制”，而不是再造一套执行系统。
+
+公开依据（可查）：SWE-bench Verified（https://www.swebench.com/verified.html）、EVMbench（https://cdn.openai.com/evmbench/evmbench.pdf）、Codex System Card（https://cdn.openai.com/pdf/8df7697b-c1b2-4222-be00-1fd3298f351d/codex_system_card.pdf）、OpenAI App Server 架构文档（https://openai.com/index/unlocking-the-codex-harness/）。
+
+## 关于“Assistant Desk 是不是强加概念”
+
+这是必须直面的拷问。
+
+我们并不是先造了 `Assistant Desk`，再反过来证明它有意义。
+相反，我们先面对一个第一性问题：
+
+> 项目资产和助理资产，到底要不要有清晰边界？
+
+如果不要边界，最简单的做法是在项目里放一个隐藏目录。
+短期确实能跑，但长期会稳定出现三个后果：
+
+1. 助理长期资产被项目生命周期绑死，迁移、复用、审计都变重。
+2. 运行态脏数据更容易污染项目仓库，协作噪声持续累积。
+3. 中间层为了兜这些混杂问题，会逐步长成“第二套任务系统”。
+
+`Assistant Desk` 解决的不是命名问题，也不是目录美观问题，而是资产边界问题：
+
+- 项目资产归项目（代码、文档、规则、SPEC）。
+- 助理资产归助理（身份、风格、记忆、对话、运行态）。
+- 中间层只负责把两者与官方能力接好，而不是吞掉两者。
+
+所以结论不是“这个概念听起来高级，所以保留”，而是：
+
+> 当产品目标是长期协作而不是一次性会话时，`Assistant Desk` 是最小必要结构，不是概念包装。
+
+## 产品结构（用户视角）
+
+从用户视角，`work-ally` 可以理解为四层：
+
+1. 项目工作现场：代码、文档、规则、任务产物。
+2. 助理办公桌：助理自己的长期资产和运行边界。
+3. `work-ally`：负责桥接、编排、审批与回送。
+4. 官方 Codex：负责推理、执行、线程与工具能力。
+
+你不需要理解底层实现细节；你只需要得到一个结果：
+无论在电脑前还是远程入口，面对的都是同一个项目连续工作流，而不是一堆彼此割裂的会话。
+
+## 它最适合什么场景
+
+`work-ally` 在以下场景价值最高：
+
+- 你不可能一直守在电脑前，但项目必须持续推进。
+- 你需要稳定的多角色协作，而不是临时聊天堆叠。
+- 你需要明确的审批边界、结果回送和可追溯留痕。
+- 你希望复用官方 Codex 能力，同时保持项目协作秩序。
+
+## 它不打算做什么
+
+`work-ally` 不做这些事：
+
+- 不替代官方 Codex 产品本身。
+- 不做重型多 Agent 平台。
+- 不在中间层重建一套会话脑、任务脑、状态机平台。
+- 不为了“看起来完整”而持续加厚核心。
+
+另外，当前有一条明确的用户承诺：
+
+> `work-ally` 暂不支持用户侧“定时任务”能力。
+
+也就是说，默认不会在你不触发时自行发起一轮任务执行；
+除非你主动发起交互，否则不会在后台持续跑任务、消耗执行资源。
+
+## 最后一条产品原则
+
+所有工具都该先回答“痛点是什么”，再回答“功能是什么”。
+
+`work-ally` 的产品原则始终不变：
+
+> 先解决真实协作痛点，再设计最小必要结构；
+> 先守住边界，再扩能力；
+> 能复用官方能力的，绝不在中间层重造一套。
+
+一句话总结：
+
+`work-ally` 不是为了引入概念而存在，而是为了让项目协作在真实世界里持续、清晰、可控地向前推进。