@jun133/athlete 0.0.5 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jun133/athlete",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "A global terminal AI coding assistant.",
   "keywords": [
     "athlete",
@@ -47,6 +47,7 @@
     "@playwright/mcp": "^0.0.70",
     "@types/adm-zip": "^0.5.8",
     "adm-zip": "^0.5.17",
+    "better-sqlite3": "^12.8.0",
     "cfb": "^1.2.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.1",
@@ -67,6 +68,7 @@
     "xlsx": "^0.18.5"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^24.5.2",
     "tsup": "^8.5.0",
     "tsx": "^4.20.5",

package/scripts/postinstall-playwright.mjs

@@ -34,20 +34,20 @@ if ((result.status ?? 1) !== 0) {
   console.warn(message);
 }
 
-function resolveInstallTarget(rawValue) {
-  switch (String(rawValue ?? "").trim().toLowerCase()) {
-    case "chrome":
-      return "chrome";
+function resolveInstallTarget(rawValue) {
+  switch (String(rawValue ?? "").trim().toLowerCase()) {
+    case "chrome":
+      return "chrome";
     case "firefox":
       return "firefox";
     case "webkit":
       return "webkit";
-    case "msedge":
-      return "msedge";
-    default:
-      return "chromium";
-  }
-}
+    case "msedge":
+      return "msedge";
+    default:
+      return "chromium";
+  }
+}
 
 function resolvePlaywrightCliPath() {
   const packageJsonPath = require.resolve("playwright/package.json");

package/spec/README.md

@@ -1,56 +1,64 @@
 # Athlete SPEC
 
-`spec/` 是 Athlete 当前唯一的规范与维护文档源。
+`spec/` 现在是 Athlete 的主缰绳。
 
-这里描述的是：
+这里不再只是“实现之后的说明书”，而是：
 
-- 项目现在已经做到什么
-- 当前架构如何组织
-- 关键规则和边界是什么
-- 维护时应该改哪一层
+- 人类审阅项目方向的主入口
+- AI 实现代码时必须对齐的规则源
+- 文档驱动开发与测试驱动开发的共同约束层
 
-这里不负责：
+## 怎么读
 
-- 历史演进叙事
-- 营销式介绍
-- 运行产物归档
+Athlete 现在把文档分成两层：
 
-## 单一真相源规则
+### 1. `用户审阅/`
 
-从现在开始：
+给人类看。
 
-- 规范、原则、模块边界、维护说明统一写在 `spec/`
-- 根目录 `README.md` 只保留用户入口和高层说明
-- 根目录 `validation/` 只保留验证产物，不再承担规范文档职责
+这里回答：
 
-## 阅读顺序
+- 这个项目现在到底想成为什么
+- 当前用户是谁
+- 哪些原则是不能动的
+- 哪些能力已经在范围内
+- 为什么这个系统不是“一个单打独斗的聊天牛马”
 
-1. `principles/README.md`
-2. `overview/产品定义.md`
-3. `overview/v0范围.md`
-4. `architecture/总体架构.md`
-5. `architecture/状态与真相源.md`
-6. `architecture/运行时循环.md`
-7. `modules/`
-8. `interfaces/`
-9. `implementation/`
-10. `testing/`
-11. `adr/`
+这层尽量不用技术黑话堆砌。
 
-## 目录说明
+### 2. `技术实现/`
 
-- `principles/`: 架构宪法与工程铁律
-- `overview/`: 产品定义、范围、边界
-- `architecture/`: 总体架构、真相源、主循环
-- `modules/`: 模块职责与约束
-- `interfaces/`: 核心接口契约
-- `repo/`: 仓库级规则与流程
-- `implementation/`: 当前目录与代码映射
-- `testing/`: 测试策略与 fail-first 列表
-- `adr/`: 关键架构决策记录
+给实现和维护看。
 
-## 文档要求
+这里回答：
 
-1. 只写现状，不写过时历史说明。
-2. 如果文档与 `src/` 当前实现冲突，以当前实现为准，并及时改文档。
-3. 同类说明只保留一份，不并行维护 `docs/` 和 `spec/` 两套说法。
+- 真相源在哪里
+- 总体架构怎么分层
+- 主循环和总指挥调度怎么衔接
+- 宿主边界、配置、扩展、控制面、通道怎么接
+- 仓库级规则、测试策略和代码地图是什么
+
+这层是代码实现、测试设计和后续重构的硬约束。
+
+## 当前阅读顺序
+
+1. `用户审阅/README.md`
+2. `用户审阅/产品定位.md`
+3. `用户审阅/系统全景.md`
+4. `用户审阅/项目范围.md`
+5. `用户审阅/宪法原则/`
+6. `技术实现/README.md`
+7. `技术实现/总体架构.md`
+8. `技术实现/状态与真相源.md`
+9. `技术实现/主循环与调度.md`
+10. `技术实现/关键模块/`
+11. `技术实现/仓库约束/`
+12. `技术实现/代码地图/`
+
+## 文档规则
+
+1. 文档优先描述当前真实项目，不写“如果以后也许会这样”的空话。
+2. 用户审阅文档优先帮助人理解方向，不被实现细枝末节淹没。
+3. 技术实现文档优先约束代码和测试，不写营销语。
+4. 一个文件只负责一件主要事情；能拆目录就拆目录，能拆文件就拆文件。
+5. 旧文档结构如果已经妨碍当前理解，可以直接删掉，不为历史目录保活。

package/spec//346/212/200/346/234/257/345/256/236/347/216/260/README.md

@@ -0,0 +1,29 @@
+# 技术实现
+
+这一层不是给路人看的。
+
+它直接服务三件事：
+
+1. 文档驱动开发
+2. 测试驱动开发
+3. 代码重构时的边界裁决
+
+## 这一层要回答什么
+
+这里必须清楚回答：
+
+- 总体分层是什么
+- 哪些状态是正式真相源
+- lead 主循环和总指挥调度怎么衔接
+- tools / skills / MCP / host 怎么接
+- CLI、Telegram、微信这些宿主各自负责什么
+- 仓库级规则和测试策略是什么
+
+## 当前阅读顺序
+
+1. `总体架构.md`
+2. `状态与真相源.md`
+3. `主循环与调度.md`
+4. `关键模块/`
+5. `仓库约束/`
+6. `代码地图/`

package/spec//346/212/200/346/234/257/345/256/236/347/216/260//344/270/273/345/276/252/347/216/257/344/270/216/350/260/203/345/272/246.md

@@ -0,0 +1,60 @@
+# 主循环与调度
+
+## 当前主循环不是单兵循环
+
+Athlete 的 turn 入口仍然是主 Agent turn loop，但每次 lead turn 之前都会先经过总指挥调度层。
+
+当前关键接线：
+
+- `src/orchestrator/leadLoop.ts`
+- `src/orchestrator/leadInput.ts`
+- `src/orchestrator/terminal.ts`
+- `src/orchestrator/prepareLeadTurn.ts`
+- `src/orchestrator/analyze.ts`
+- `src/orchestrator/taskPlanning.ts`
+- `src/orchestrator/progress.ts`
+- `src/orchestrator/route.ts`
+- `src/orchestrator/dispatch.ts`
+
+## 当前 lead turn 流程
+
+1. 读取项目上下文
+2. 分析本次输入的 objective 和复杂度
+3. 从控制面加载当前相关任务进度
+4. 必要时补最小任务图
+5. 计算 ready / blocked / active / merge 状态
+6. 决定由 lead、subagent、teammate 还是 background 执行
+7. 如果需要 dispatch，就先完成正式派发
+8. 如果 delegated work 仍在推进，直接进入正式 wait 结果，不再进入普通 lead turn
+9. 只有当机器状态明确给出 `self_execute` 时，才进入普通 lead turn
+10. lead 执行时必须带上正式阶段输入，不能把 merge / implementation 混成自由发挥
+
+## route 当前做什么
+
+`src/orchestrator/route.ts` 当前会优先判断：
+
+- 是否有控制面冲突
+- 是否有 lead 已经在执行的正式阶段
+- 是否有 merge 任务
+- 是否应该先 survey
+- 是否适合跑 background
+- 是否适合派 teammate
+- 是否应该正式等待已在跑或已保留的 delegated work
+- 否则由 lead 继续执行
+
+## 这层的意义
+
+这层的意义不是“做得更复杂”，而是把 Athlete 从单兵工作流推进成总指挥工作流：
+
+- lead 不再总是自己直接干
+- 系统知道什么时候该分、该派、该等、该合
+- 调度判断来自机器状态，不靠 prompt 记忆
+- dispatch / wait / merge 不再只是 pre-turn 提示，而是主路径上的正式状态推进
+
+## 当前约束
+
+1. 调度判断必须基于统一真相源。
+2. orchestrator 负责组织和路由，不负责具体文件改写。
+3. 宿主不允许偷偷复写自己的调度规则。
+4. 如果任务状态和执行现实冲突，优先暴露冲突，不做假装顺滑。
+5. `wait_for_existing_work` 必须产出正式 pause transition，不能继续偷偷落入普通 lead turn。

package/spec//346/212/200/346/234/257/345/256/236/347/216/260//344/273/223/345/272/223/347/272/246/346/235/237//345/274/200/345/217/221/350/247/204/345/210/231.md

@@ -0,0 +1,14 @@
+# 开发规则
+
+## 当前目标
+
+这份规则服务的是：让 Athlete 在继续快速演进时，仍然保持清楚、可改、可验证。
+
+## 当前规则
+
+1. 一个文件只做一件主要事情。
+2. 能拆目录就拆目录，能拆文件就拆文件。
+3. 新能力优先长在清晰边界上，不优先塞进已有大文件。
+4. 宿主层、核心层、控制面要分清。
+5. 旧结构如果已经妨碍当前主干，可以直接清理，不为旧残余保活。
+6. 文档、测试、实现三者必须相互对齐。

package/spec//346/212/200/346/234/257/345/256/236/347/216/260//344/273/223/345/272/223/347/272/246/346/235/237//346/234/254/345/234/260/345/221/275/344/273/244/344/270/216/346/265/201/347/250/213.md

@@ -0,0 +1,20 @@
+# 本地命令与流程
+
+## 当前核心命令
+
+- `npm.cmd run check`
+- `npm.cmd test`
+- `npm.cmd run build`
+- `node dist\\cli.js`
+
+## 当前推荐流程
+
+1. 先更新文档
+2. 先补失败测试
+3. 再改实现
+4. 最后跑完整验证
+
+## 当前要求
+
+- Windows 环境优先使用 `npm.cmd`
+- 用户可见入口优先验证 CLI、Telegram、微信主路径

package/spec//346/212/200/346/234/257/345/256/236/347/216/260//344/273/223/345/272/223/347/272/246/346/235/237//346/265/213/350/257/225/347/255/226/347/225/245.md

@@ -0,0 +1,48 @@
+# 测试策略
+
+## 当前目标
+
+测试不是覆盖率装饰，而是用来保护主干结构。
+
+## 当前优先保护对象
+
+1. 主 Agent 耐跑能力
+2. 总指挥调度语义
+3. 控制面真相源
+4. 宿主运行边界
+5. 配置治理
+6. 宿主行为回归
+
+## 当前测试分层
+
+### 结构护栏
+
+用于防止架构回退。
+
+例如：
+
+- 宿主不再直连 raw turn
+- 宿主不再直连 raw runtime registry
+- 关键文件保持单一职责
+
+### 行为回归
+
+用于保护用户看得见的能力。
+
+例如：
+
+- one-shot closeout
+- interactive 行为
+- Telegram / 微信 `/stop`
+- 文件回传
+- visible events
+
+### 真相源回归
+
+用于保护 session、checkpoint、SQLite ledger 和配置入口不被旁路替代。
+
+## 当前规则
+
+1. 先写失败测试，再写实现。
+2. 新文档路径和新模块边界如果会影响测试，测试要一起迁移。
+3. 文档驱动和测试驱动要一起工作，不能一个更新、另一个失效。

package/spec//346/212/200/346/234/257/345/256/236/347/216/260//344/273/243/347/240/201/345/234/260/345/233/276//347/233/256/345/275/225/345/210/260/344/273/243/347/240/201/346/230/240/345/260/204.md

@@ -0,0 +1,51 @@
+# 目录到代码映射
+
+## 当前主目录地图
+
+### 核心执行系统
+
+- `src/agent/`
+  - turn、session、checkpoint、verification、acceptance、runtime stats
+- `src/orchestrator/`
+  - 输入分析、任务规划、进度读取、路由、派发
+- `src/tools/`
+  - 内建工具与 runtime tool registry
+- `src/skills/`
+  - skill catalog、matching、loading、workflow guards
+- `src/mcp/`
+  - 外部能力接入
+- `src/control/ledger/`
+  - SQLite 控制面仓库
+- `src/tasks/` / `src/team/` / `src/execution/` / `src/worktrees/`
+  - 各控制面实体的实现层
+
+### 宿主运行边界
+
+- `src/host/`
+  - 共享 session 入口
+  - 共享 turn 入口
+  - 共享 host extra tool 注入
+
+### 宿主适配层
+
+- `src/cli/`
+  - commander、one-shot、session 命令
+- `src/interaction/`
+  - 共享交互驱动
+- `src/ui/` / `src/shell/cli/`
+  - CLI 展示层
+- `src/telegram/`
+  - Telegram 通道
+- `src/weixin/`
+  - 微信通道
+
+## 当前关键文件
+
+- `src/orchestrator/prepareLeadTurn.ts`
+- `src/orchestrator/route.ts`
+- `src/orchestrator/taskLifecycle.ts`
+- `src/host/turn.ts`
+- `src/host/boundTurn.ts`
+- `src/config/store.ts`
+- `src/telegram/turnRunner.ts`
+- `src/weixin/turnRunner.ts`

package/spec//346/212/200/346/234/257/345/256/236/347/216/260//345/205/263/351/224/256/346/250/241/345/235/227/Telegram/347/247/201/350/201/212.md

@@ -0,0 +1,31 @@
+# Telegram私聊
+
+## 当前定位
+
+Telegram 是 Athlete 的私聊宿主之一。
+
+它负责把 Telegram Bot API 接到统一主路径上，而不是自己重造 runtime。
+
+## 当前能力
+
+- `telegram serve`
+- 私聊白名单
+- `/stop`
+- session 绑定
+- 可见事件输出
+- 文件下载
+- 文件回传
+
+## 当前关键实现
+
+- `src/telegram/cli.ts`
+- `src/telegram/service.ts`
+- `src/telegram/turnRunner.ts`
+- `src/telegram/sendFileTool.ts`
+- `src/telegram/deliveryQueue.ts`
+
+## 当前约束
+
+1. Telegram turn 必须经 `src/host/`。
+2. Telegram 只保留 transport、delivery、typing、attachment、stop 语义。
+3. send file 是 host extra tool，不是 Telegram 自己拼 runtime。

package/spec//346/212/200/346/234/257/345/256/236/347/216/260//345/205/263/351/224/256/346/250/241/345/235/227//344/272/244/344/272/222/347/273/210/347/253/257.md

@@ -0,0 +1,26 @@
+# 交互终端
+
+## 当前定位
+
+交互终端是一个宿主外壳，不是核心真相源。
+
+## 当前边界
+
+- `src/ui/interactive.ts`
+- `src/interaction/`
+- `src/shell/cli/`
+
+## 当前职责
+
+- 输入输出
+- 本地命令
+- turn 展示
+- interrupt
+- quit / exit guard
+- runtime summary 展示
+
+## 当前约束
+
+1. 交互终端不能直接依赖 raw turn。
+2. 它必须通过 `src/host/` 进入核心。
+3. 展示层不能偷偷保存平行 runtime 状态。

package/spec//346/212/200/346/234/257/345/256/236/347/216/260//345/205/263/351/224/256/346/250/241/345/235/227//345/221/275/344/273/244/350/241/214/344/272/247/345/223/201/351/235/242.md

@@ -0,0 +1,27 @@
+# 命令行产品面
+
+## 当前启动链
+
+- fast path
+- lightweight path
+- full runtime path
+
+## 当前产品目标
+
+- `--version`、`help`、`config path` 快速返回
+- 配置坏了时仍给出修复入口
+- full runtime 命令才拉起重模块
+
+## 当前关键文件
+
+- `src/cli.ts`
+- `src/cli/program.ts`
+- `src/cli/commands/`
+- `src/cli/runtime.ts`
+- `src/cli/oneShot.ts`
+
+## 当前约束
+
+1. CLI 产品面不定义核心真相源。
+2. one-shot 和 interactive 都必须走 `src/host/`。
+3. 顶层 CLI 入口不能重新长成总控大文件。

package/spec//346/212/200/346/234/257/345/256/236/347/216/260//345/205/263/351/224/256/346/250/241/345/235/227//345/244/232/346/231/272/350/203/275/344/275/223/350/260/203/345/272/246.md

@@ -0,0 +1,79 @@
+# 多智能体调度
+
+## 当前定位
+
+Athlete 现在不是三套执行者并存，而是一套正式 execution lane 体系：
+
+- `agent lane`
+- `command lane`
+
+`subagent` 和 `teammate` 不再是两套生命周期，它们只是 `agent lane` 的两种 profile：
+
+- `subagent`: 同步、轻量、干净上下文
+- `teammate`: 异步、可复用身份、可恢复 session
+
+`background` 是 `command lane` 的 profile。
+
+## 当前正式真相源
+
+- `src/execution/`
+- `src/control/ledger/executionRepo.ts`
+- `src/orchestrator/dispatch.ts`
+- `src/orchestrator/progress.ts`
+- `src/orchestrator/taskLifecycle.ts`
+
+lead 面对 delegated work 时，正式观察对象是 execution record，不再直接拼接：
+
+- memory-only subagent 特例
+- teammate 持久 poll loop
+- background job 通知消息
+
+## 当前统一生命周期
+
+所有 execution lane 共享同一组正式状态：
+
+- `queued`
+- `running`
+- `paused`
+- `completed`
+- `failed`
+- `aborted`
+
+lane 差异只体现在驱动方式，不体现在生命周期制度。
+
+## 当前统一主路径
+
+1. orchestrator 决定任务交给哪条 lane/profile
+2. `dispatch` 创建 execution record
+3. 如需异步执行，统一通过 `__worker__ run --execution-id <id>` 拉起 worker
+4. execution worker 领取 task/worktree/inbox 上下文
+5. execution 结束后统一写 closeout，并通过 `execution_closeout` 回到 lead inbox
+6. `progress` 和 `route` 根据 execution 状态决定 wait / merge / reconcile
+
+## 当前共享制度
+
+### task 绑定
+
+- execution 可显式绑定 `taskId`
+- task 不再只靠 teammate/background 私有状态判断“谁在干”
+
+### worktree 绑定
+
+- task-bound agent execution 统一走 `prepareExecutionTaskContext`
+- worktree 不再是 teammate 独占语义
+
+### inbox / result handoff
+
+- 异步 execution 完成、失败、暂停都走统一 `execution_closeout`
+- background 不再只是“跑完发一条背景消息”
+
+### session / 恢复
+
+- subagent 现在也留下正式 session 与 execution closeout
+- teammate 复用 identity/session，但一次 execution 只负责一次正式派工
+
+## 当前约束
+
+1. lead 等待 delegated work 时，依据 execution state，不依据三套私有 worker 状态。
+2. 异步 worker 只允许统一 CLI 协议入口，不再保留 lane 私有子命令。
+3. 新执行能力优先作为 lane/profile 扩展，不再再造第四套执行制度。

package/spec//346/212/200/346/234/257/345/256/236/347/216/260//345/205/263/351/224/256/346/250/241/345/235/227//345/256/277/344/270/273/350/277/220/350/241/214/350/276/271/347/225/214.md

@@ -0,0 +1,74 @@
+# 宿主运行边界
+
+## 目标
+
+`src/host/` 是核心执行系统对宿主暴露的正式接入点。
+
+它存在的目的，是让 CLI、interactive、Telegram、微信和未来其他宿主走同一条主路径。
+
+## 当前能力
+
+### session 入口
+
+- `createHostSession`
+- `createPersistedSession`
+- `loadLatestSession`
+- `ensureBoundSession`
+- `persistBoundSession`
+
+当前 contract：
+
+- 宿主 binding 只保存 “我绑的是哪个 `sessionId`”
+- 真正 session 内容只能从 `SessionStore` 读取
+- `ensureBoundSession(...)` 只会在 `session not found` 时重建 formal session
+- 如果 session snapshot 损坏或 schema 不支持，宿主必须失败暴露，不能偷偷发明新 session
+
+### turn 入口
+
+- `runHostTurn`
+- `runBoundHostTurn`
+
+### runtime tools 入口
+
+- `createHostToolRegistry`
+
+## 当前宿主可注入的扩展
+
+- host identity
+- callbacks
+- extra tools
+
+例如：
+
+- Telegram send file
+- 微信 send file
+
+## 当前正式 host tool 路径
+
+`src/host/toolRegistry.ts` 现在只做一件事：
+
+- 把宿主 extra tool 收成 `ToolRegistrySource(kind=host)`
+- 再统一交给 `createRuntimeToolRegistry(...)`
+
+也就是说，宿主 extra tool 的正式路径是：
+
+`host tool -> host source -> shared runtime registry -> governance -> exposure`
+
+而不是：
+
+`host tool -> 直接拼进 runtime tools 列表`
+
+## 当前宿主注入规则
+
+1. extra tool 必须仍然带治理语义。
+2. host source 会把来源标记成 `host`，不能再伪装成 builtin。
+3. host 只能通过这里进入 shared registry，不能自己私下再造第二个 registry。
+4. host 注入失败必须暴露在注册或治理边界，不能静默忽略。
+
+## 当前硬约束
+
+1. 宿主不允许直接 import raw `runManagedAgentTurn(...)`。
+2. 宿主不允许直接 import raw `createRuntimeToolRegistry(...)`。
+3. pause / abort / error / closeout 必须通过这里统一收口。
+4. `src/host/` 不能新造平行真相源。
+5. extra tool 只能经 `createHostToolRegistry(...)` 进入 runtime，不能绕开 host source。

package/spec//346/212/200/346/234/257/345/256/236/347/216/260//345/205/263/351/224/256/346/250/241/345/235/227//345/267/245/344/275/234/345/214/272/344/270/216/345/271/266/350/241/214/351/232/224/347/246/273.md

@@ -0,0 +1,55 @@
+# 工作区与并行隔离
+
+## 当前定位
+
+worktree 是 execution lane 的共享隔离层，不是 teammate 私有机制。
+
+## 当前作用
+
+- 给 task-bound execution 提供独立目录
+- 让并行 lane 不互相踩改动
+- 把 task、execution、实际工作目录明确绑在一起
+
+## 当前关键实现
+
+- `src/worktrees/store.ts`
+- `src/execution/taskBinding.ts`
+- `src/orchestrator/taskLifecycle.ts`
+
+## 当前正式关系
+
+### task
+
+回答：
+
+- 做什么
+- 依赖谁
+- 当前是否完成
+
+### execution
+
+回答：
+
+- 谁在执行
+- 现在是 `queued/running/paused/completed/failed/aborted` 哪一种
+- 结果是否已经正式 closeout
+
+### worktree
+
+回答：
+
+- 在哪里做
+- 这条目录车道是否还有效
+
+## 当前主路径
+
+1. lane 绑定到 `taskId`
+2. `prepareExecutionTaskContext` 统一处理 claim 与 worktree attach
+3. execution 在 worktree cwd 里运行
+4. execution closeout 后，task / worktree / result handoff 分别按正式状态收口
+
+## 当前约束
+
+1. worktree 绑定来自正式 task/execution 主路径，不来自某个 lane 的私有循环。
+2. removed worktree 不能继续被当成 active execution lane。
+3. teammate 与 subagent 的 task-bound agent execution 都可以绑定 worktree；不再保留 teammate 独占语义。