@jun133/athlete 0.0.4 → 0.0.6

package/spec/modules/config-system.md

@@ -1,51 +0,0 @@
-# config system
-
-## 作用
-
-配置系统负责统一读取 Athlete 的运行参数，并把项目级默认值、用户配置和环境变量合并成最终 runtime config。
-
-## 当前范围
-
-- API key / base URL / model
-- mode
-- paths
-- MCP 总开关与 server 配置
-- Playwright MCP repo 级默认值
-- context / continuation / read limits 等运行阈值
-
-## 当前规则
-
-1. 配置入口统一。
-2. 业务模块不直接散读环境变量。
-3. 用户能从 runtime config 理解当前行为从哪来。
-4. 项目级默认值允许放在 `.athlete/.env`，但仍由统一配置入口解析。
-
-## Playwright MCP 当前事实
-
-当前支持的 repo 级 Playwright MCP 环境变量：
-
-- `ATHLETE_MCP_ENABLED`
-- `ATHLETE_MCP_PLAYWRIGHT_ENABLED`
-- `ATHLETE_MCP_PLAYWRIGHT_BROWSER`
-- `ATHLETE_MCP_PLAYWRIGHT_HEADLESS`
-- `ATHLETE_MCP_PLAYWRIGHT_OUTPUT_MODE`
-- `ATHLETE_MCP_PLAYWRIGHT_SAVE_SESSION`
-
-当前仓库默认行为：
-
-- Playwright MCP 在项目级 `.athlete/.env` 中默认启用
-- 默认浏览器为 `chrome`
-- 默认不是 headless
-- 默认 output mode 为 `file`
-- 默认 save session 为开启
-
-## 路径约定
-
-当前 Playwright MCP 状态目录：
-
-- `.athlete/playwright-mcp/config.json`
-- `.athlete/playwright-mcp/profile/`
-- `.athlete/playwright-mcp/output/`
-- `.athlete/playwright-mcp/legacy-root-artifacts/`
-
-这些路径由配置系统和 `src/mcp/playwright/` 统一导出，不允许在调用侧随意拼接。

package/spec/modules/interactive-terminal.md

@@ -1,112 +0,0 @@
-# interactive terminal
-
-## 作用
-
-交互终端是 Athlete 的表现层外壳，不是控制面真相源。
-
-## 当前真实能力
-
-### 当前分层
-
-- `src/interaction/`: 共享交互控制层
-- `src/shell/cli/`: CLI shell 适配层
-- `src/ui/`: CLI 文本格式化、runtime summary 和兼容导出
-
-### 共享交互控制层职责
-
-- 驱动交互 session loop
-- 处理普通输入和 multiline 分支
-- 处理本地命令路由
-- 管理 turn in-flight 状态与 abort controller 生命周期
-- 接线 `runManagedAgentTurn`
-- 维护当前 session 的内存态，并在 turn 完成后接收最新 session
-
-### 当前 CLI shell 职责
-
-- 提供 persistent input / multiline input
-- 绑定终端 interrupt
-- 展示 assistant 流式输出
-- 展示 tool 调用和状态消息
-- 展示 banner、launch hints、dim/warn/plain/stderr 风格
-- 展示当前 session 的 runtime summary
-
-## 规则
-
-1. UI 不能反向定义 task、protocol、worktree、checkpoint、runtimeStats 等控制面事实。
-2. spinner、stream renderer、本地命令格式化都只属于表现层。
-3. Athlete 可以替换 UI，但不能因此破坏 runtime kernel。
-4. `/runtime`、`/stats`、`/仪表盘` 只是 `SessionRecord.runtimeStats` 的只读 summary 视图。
-5. UI 可以读取并展示真相源，但不能绕过真相源另造状态。
-6. 交互 session loop 不能直接绑死 `readline`、`process.stdin/stdout`、`chalk` 这类 CLI 细节。
-7. shell 只能提供输入、输出和 turn 展示适配，不能自己发明 task / protocol / runtime 真相。
-## 当前本地命令入口
-
-- `/session`
-- `/config`
-- `/todos`
-- `/tasks`
-- `/team`
-- `/background`
-- `/worktrees`
-- `/inbox`
-- `/runtime`
-- `/stats`
-- `/仪表盘`
-- `/reset`
-
-## Runtime Summary 展示范围
-
-当前交互态最小 runtime summary 包含：
-
-- session health
-- model request count
-- model wait total
-- tool call count
-- tool duration total
-- yield / continuation / recovery / compression count
-- externalized result count / bytes
-- top tools
-
-## Reset Boundary
-
-- `/reset` 是显式 destructive local command，不是普通的窗口关闭动作。
-- `/reset` 清空当前项目 `.athlete/` 下的运行时状态，但保留 `.athlete/.env` 和 `.athlete/.env.example`。
-- `/reset` 还会删除当前项目相关的持久化 session，因此 `resume` 不应恢复已经 reset 掉的运行时。
-- `/reset` 会尽量先通过正式 worktree / process 清理路径收尾，再删除状态目录。
-- reset 行为必须落在 runtime / project state 层，UI 只能触发它，不能自己维护一套平行 reset 状态。
-
-## 当前边界
-
-### 共享边界
-
-- `InteractiveSessionDriver`: 共享交互控制器
-- `InteractionShell`: 壳适配接口
-- `ShellInputPort`: 普通输入 / multiline 输入 / interrupt 订阅
-- `ShellOutputPort`: info / warn / plain / dim / interrupt 等展示输出
-- `InteractionTurnDisplay`: turn 期间的流式展示适配
-
-### 当前 CLI 接线
-
-- `src/ui/interactive.ts`: CLI 入口薄壳，只负责组装 shell、打印 intro、启动 driver
-- `src/shell/cli/readlineInput.ts`: CLI 输入适配
-- `src/shell/cli/output.ts`: `chalk` + stdio 输出适配
-- `src/shell/cli/turnDisplay.ts`: spinner + stream renderer 适配
-- `src/interaction/localCommands.ts`: 共享本地命令语义
-
-## 当前展示边界
-
-交互终端当前只负责把这些状态展示清楚：
-
-- task board
-- teammate 状态
-- background 状态
-- skill load 状态
-- runtime summary
-
-但它不负责发明这些状态。
-
-## 未来方向
-
-- 桌面壳应直接实现 `InteractionShell` 契约，而不是复用 CLI 的 `readline` / stdio 细节。
-- 桌面壳可以自己提供输入框、停止按钮、流式消息区和状态面板。
-- 只要继续复用 `InteractiveSessionDriver`，桌面壳与 CLI 壳就应共享同一套本地命令、turn 驱动和中断语义。

package/spec/modules/lightweight-context-runtime.md

@@ -1,63 +0,0 @@
-# lightweight context runtime
-
-## 目标
-
-这一层负责让 Athlete 在长任务里继续跑，但不要把 prompt 和 session 越跑越重。
-
-## 运行时约定
-
-1. system prompt 按两层正式组装：
-   - `Static operating layer`
-   - `Dynamic runtime layer`
-2. 静态层放稳定规则、模式规则、身份规则、项目说明。
-3. 动态层放 cwd / root / date / taskState / todo / verification / task board / team / worktree / protocol / background / skill runtime。
-4. 压缩后的会话总结不再直接拼回静态层，而是追加为 `Compressed conversation memory`。
-
-## 大 tool result 外置化
-
-1. 当 tool output 超过约 `12,000` chars 或 `16 KB` 时，进入外置化路径。
-2. 原始 output 落盘到项目 state root 下：
-   - `.athlete/tool-results/<sessionId>/<timestamp>-<tool>-<hash>.json|txt`
-3. session 里保留的 tool message 只存轻量引用：
-   - `externalized: true`
-   - `storagePath`
-   - `summary`
-   - `preview`
-   - `byteLength`
-   - `charLength`
-4. 小结果继续走原来的 inline message 路径，不做无差别外置化。
-5. 当 agent 读取 `.athlete/tool-results/...` 中的 artifact 文件时，`read_file` 默认返回紧凑摘要视图；只有显式 line range 读取才继续走原始逐行查看路径。
-
-## 闭环要求
-
-1. continuation 继续使用 session 中的轻量 tool message，而不是重新塞回原始大正文。
-2. contextBuilder 在压缩历史时继续保留 `storagePath` 和预览信息。
-3. recovery 的 context shrink 也要保住结构化引用，不能把它打回不可追踪的大字符串。
-4. session 保存和加载后，外置化引用仍然可以恢复到落盘文件。
-5. 已通过 streaming delta 发出的 assistant 文本不会在 finalize 阶段再次整段重放。
-
-## 验证方式
-
-1. fail-first 测试：
-   - `tests/runtime-lightweight-context.test.ts`
-2. 核心回归：
-   - `npm run test:build`
-   - `npm run test:core`
-3. 真实 API：
-   - `npm run verify:runtime-context-api`
-## Checkpoint Runtime Contract
-
-- `SessionRecord` now persists a structured `checkpoint` inside the existing session truth source.
-- `checkpoint` is a runtime summary, not a transcript dump. It carries:
-  - objective
-  - completedSteps
-  - currentStep
-  - nextStep
-  - recentToolBatch
-  - flow phase (`active / continuation / resume / recovery`)
-  - priorityArtifacts (externalized tool-result refs, previews, pending paths)
-- continuation, reload/resume, and dynamic prompt rendering must all consume the same checkpoint instead of inventing separate recovery hints.
-- objective changes reset checkpoint progress so old work does not pollute the new task.
-- externalized tool results remain the preferred recoverable context, and checkpoint keeps the references lightweight.
-- fail-first test for this layer: `tests/runtime-checkpoint-resume.test.ts`
-- real API verification entry for this layer: `npm run verify:runtime-checkpoint-api`

package/spec/modules/provider-adapter.md

@@ -1,20 +0,0 @@
-# provider adapter
-
-## 作用
-
-provider adapter 负责把 Athlete 的请求发送到具体模型服务。
-
-## 当前策略
-
-- 优先 OpenAI-compatible
-- 运行时对网络错误、超时、上下文过长有恢复策略
-
-## 规则
-
-1. provider 能换，主循环不跟着重写。
-2. provider 问题先在 adapter 层处理，不外溢到任务语义层。
-3. 模型 fallback 属于运行时策略，不属于业务模块。
-
-## 下一阶段要求
-
-总指挥层不依赖某一家 provider 特性。

package/spec/modules/runtime-metrics.md

@@ -1,132 +0,0 @@
-# runtime metrics
-
-## 作用
-
-这一层开始，Athlete 的 session 会持久化结构化 `runtimeStats`，
-作为正式运行态仪表盘的真相源。
-
-它回答的是：
-
-- 这次 session 一共发了多少次 provider request
-- 模型等待总耗时是多少
-- tool 一共调用了多少次、各自累计耗时多少
-- yield / continuation / recovery / compression 各发生了多少次
-- 有多少 tool result 被 externalize，以及累计字节数是多少
-- provider usage 是 available、partial 还是 unavailable
-
-## 真相源位置
-
-- `SessionRecord.runtimeStats`
-- 仍然持久化在既有 session JSON 文件里
-- 不新建平行 JSON 真相源
-
-## 当前结构
-
-`runtimeStats` 当前包含：
-
-- `version`
-- `model.requestCount`
-- `model.waitDurationMsTotal`
-- `model.usage.requestsWithUsage`
-- `model.usage.requestsWithoutUsage`
-- `model.usage.inputTokensTotal`
-- `model.usage.outputTokensTotal`
-- `model.usage.totalTokensTotal`
-- `model.usage.reasoningTokensTotal`
-- `tools.callCount`
-- `tools.durationMsTotal`
-- `tools.byName`
-- `events.continuationCount`
-- `events.yieldCount`
-- `events.recoveryCount`
-- `events.compressionCount`
-- `externalizedToolResults.count`
-- `externalizedToolResults.byteLengthTotal`
-- `updatedAt`
-
-## 来源
-
-### model request
-
-- 来源：`src/agent/api.ts`
-- 统计粒度：真实 provider request attempt
-- 包括 streaming、non-streaming fallback、retry、retry fallback
-
-### tool execution
-
-- 来源：`src/agent/runTurn.ts`
-- 统计粒度：真实 runtime tool execution
-- `tools.byName` 记录每个 tool 的调用次数、累计耗时、成功次数、失败次数
-
-### yield / continuation / recovery
-
-- 来源：`src/agent/turnPersistence.ts`
-- continuation 包括：
-  - managed continuation 的内部续跑输入
-  - 用户显式 `continue` / `resume` 这类恢复输入
-
-### compression
-
-- 来源：`src/agent/runTurn.ts`
-- 当 `buildRequestContext(...)` 返回 `compressed = true` 时记一次
-
-### externalized tool results
-
-- 来源：`src/agent/runTurn.ts` + `src/agent/toolResultStorage.ts`
-- 只在 tool result 实际被 externalize 时累计
-
-## 用户入口
-
-当前最小仪表盘入口：
-
-- `/runtime`
-- `/stats`
-- `/仪表盘`
-
-这些命令只读取并格式化当前 session summary，
-不发明新的运行态事实。
-
-## 当前 summary 最少包含
-
-- model request 次数
-- model wait 总耗时
-- tool call 次数
-- tool 总耗时
-- yields / continuations / recoveries / compressions
-- externalized result count / bytes
-- top tools
-- slowest step
-- usage availability
-- session health
-
-## usage 规则
-
-- 只有 provider 明确返回 usage 时才记录 usage
-- 如果 provider 没返回 usage，summary 必须显示 `unavailable` 或 `partial`
-- 不根据字符数、消息数、模型名去估算 token
-
-## 健康状态
-
-当前 summary 会给出：
-
-- `healthy`
-- `warning`
-- `recovering`
-
-它来自 checkpoint phase、verification state、recovery 事件等正式状态的推导视图，
-不是另一份单独持久化的状态。
-
-## 真实验证
-
-当前真实 API 验证入口：
-
-- `npm run verify:runtime-observability-api`
-
-它至少要确认：
-
-- `runtimeStats` 已写进 session
-- reload session 后 `runtimeStats` 仍然存在
-- 真实 model request 被统计
-- 真实 tool call 被统计
-- 用户可读的 runtime summary 路径可用
-- lightweight context 与 checkpoint runtime 没被打坏

package/spec/modules/runtime-rules.md

@@ -1,33 +0,0 @@
-# runtime rules
-
-## 作用
-
-运行时规则是 Athlete 的机器约束层。
-
-## 当前包含
-
-- 计划先行
-- inbox 注入
-- verification 状态机
-- finalize / closeout gating
-- continuation / compression
-- tool error recovery
-
-## 不该放进来的东西
-
-- 具体任务拆分算法
-- 具体 skill 内容
-- 某个单一工具的内部实现
-
-## 当前与收口直接相关的规则
-
-- 变更型动作默认要求先 `todo_write`
-- 文件改动和 mutating shell 会把 session 推进到 verification required
-- 轻量交付物允许用定向 `read_file` / auto-readback 完成轻量验证
-- continuation 后仍然读取持久化的 `pendingPaths`，不会因为 slice 切换就忘记“还有哪些输出待验”
-- 当收口条件已满足时，task board closeout 工具会被隐藏，避免 `task_list` / `task_get` / `task_update` 无意义循环
-- 当 todo 已全部完成时，runtime 不再继续鼓励补写 `todo_write`
-
-## 下一阶段要求
-
-总指挥层可以提出“下一步做什么”，但运行时规则仍决定“现在允不允许这样做”。

package/spec/modules/session-resume-compact.md

@@ -1,49 +0,0 @@
-# session / resume / compact
-
-## 作用
-
-这一层负责保护 Athlete 的“长任务可继续”能力。
-
-## 当前能力
-
-- session 持久化
-- resume 继续最近任务现场
-- request context 压缩
-- continuation 自动续跑
-- todo / taskState / verificationState 跨 slice 持续生效
-
-## 当前边界
-
-Athlete 当前的记忆重点是：
-
-- 当前项目
-- 当前任务
-- 当前 turn 相关状态
-- 当前待验证输出 `pendingPaths`
-- 最近一次 verification 结果
-
-它不是跨项目的人格记忆。
-
-## 当前实现约束
-
-- continuation 会复用已有 session，而不是重新发明 todo / verification 状态。
-- compact 只压缩请求上下文，不抹掉任务板、todo、verification 这些真相源。
-- 收口判断可以依赖持久化的 `verificationState.pendingPaths`，不能只看当前 slice 的临时 `changedPaths`。
-
-## Resume / Reset Contract
-
-- `resume` 的语义是继续现有任务现场。
-- `quit` 只是退出当前聊天窗口，不主动清空项目运行时状态。
-- 显式 `reset` 会清空当前项目 `.athlete/` 下的运行时状态，并删除当前项目相关的持久化 session。
-- 一旦 `reset` 成功，`resume` 不应恢复已经 reset 掉的运行时。
-- 如果 objective 明确变化，checkpoint 进度必须重置，避免旧任务进度污染新任务。
-- externalized tool-result references 和 verification pending paths 仍然是优先的可恢复锚点，但 reset 会主动销毁这一层锚点。
-
-## 下一阶段要求
-
-未来可以增加更强的恢复能力，但必须遵守：
-
-1. 项目事实优先于抽象记忆。
-2. 记忆是辅助，不是第二真相源。
-3. 不能破坏现有 continuation / compact / resume 的稳定边界。
-4. destructive reset 必须保持显式、可理解、不可与普通 quit 混淆。

package/spec/modules/task-state.md

@@ -1,34 +0,0 @@
-# task state
-
-## 作用
-
-任务状态是 Athlete 控制面的核心。
-
-## 当前字段重点
-
-- `status`
-- `blockedBy`
-- `blocks`
-- `assignee`
-- `owner`
-- `checklist`
-- `worktree`
-
-## 当前规则
-
-1. `assignee` 表示应该谁做。
-2. `owner` 表示现在谁正在做。
-3. 被阻塞任务不能启动。
-4. 已完成任务不能随意重开。
-
-## 下一阶段演进方向
-
-任务系统要支持总指挥层，优先考虑增加：
-
-- 优先级
-- 父子任务
-- 重试次数
-- 产物引用
-- review / verify 要求
-
-这些演进必须建立在现有持久化任务板上，而不是另起一套任务宇宙。