@jun133/athlete 0.0.4 → 0.0.6

package/spec/architecture//346/200/273/344/275/223/346/236/266/346/236/204.md

@@ -1,111 +0,0 @@
-# 总体架构
-
-## 一句话
-
-Athlete 是一个终端里的智能体运行系统：
-
-- 一个主循环驱动模型与工具
-- 一组落盘状态构成控制面
-- 一组工具与 worker 构成执行面
-- 一层 orchestrator 负责 lead 的任务组织与派工
-
-## 当前主要分层
-
-### 1. Runtime Kernel
-
-目录：`src/agent/`
-
-负责：
-
-- turn loop
-- system prompt 组装
-- continuation / compact / recovery
-- todo / verification / runtime state
-- 最终收口
-- 轻量验证信号与 auto-readback
-
-### 2. Tool Plane
-
-目录：`src/tools/` `src/mcp/`
-
-负责：
-
-- 向模型暴露动作
-- 参数解析
-- 机器约束检查
-- 调用底层能力
-
-### 3. Skill Plane
-
-目录：`src/skills/`
-
-负责：
-
-- skill schema
-- discovery
-- matching
-- loading
-- workflow gating
-
-### 4. Control Plane
-
-目录：`src/tasks/` `src/team/` `src/background/` `src/worktrees/`
-
-负责：
-
-- 任务真相源
-- 协议真相源
-- 队友状态
-- 后台作业状态
-- worktree 状态
-
-### 5. Execution Plane
-
-负责真正干活：
-
-- 文件读写
-- shell 命令
-- 背景任务
-- teammate worker
-- worktree 目录
-- MCP 浏览器
-
-### 6. Orchestrator Layer
-
-目录：`src/orchestrator/`
-
-负责：
-
-- 复杂度判断
-- 最小任务图落盘
-- self / subagent / teammate / background 路由
-- lead slice 开始前的任务组织
-
-## 当前最重要的架构边界
-
-### 控制面
-
-回答：
-
-- 现在有哪些任务
-- 谁该做、谁在做
-- 哪些正式协作在 pending
-- 哪些后台任务在跑
-- 哪些 worktree 仍然有效
-
-### 执行面
-
-回答：
-
-- 文件怎么改
-- 命令怎么跑
-- 浏览器怎么导航
-- 某个 worker 具体在执行什么
-
-### 关键规则
-
-1. 控制面不直接改文件。
-2. 执行面不发明控制面真相。
-3. orchestrator 负责调度，不负责具体文件改写。
-4. tools 提供动作，skills 提供 workflow，二者不互相替代。
-5. 主循环只做调度；closeout、verification signal、workflow gating 这类长期规则要下沉到独立模块。

package/spec/architecture//347/212/266/346/200/201/344/270/216/347/234/237/347/233/270/346/272/220.md

@@ -1,117 +0,0 @@
-# 状态与真相源
-
-## 目标
-
-Athlete 要跑长任务、协作任务和恢复任务，关键状态不能只放在 prompt 里。
-
-必须有落盘真相源。
-
-## 当前真相源
-
-### TaskStore
-
-回答：
-
-- 有哪些任务
-- 哪些任务被阻塞
-- 谁被指派
-- 谁正在做
-- 任务绑定了哪个 worktree
-
-状态目录：`.athlete/tasks/`
-
-### TeamStore
-
-回答：
-
-- 现在有哪些 teammate
-- 各自角色和状态是什么
-
-状态文件：`.athlete/team/config.json`
-
-### ProtocolRequestStore
-
-回答：
-
-- 哪些正式协作在 pending
-- 哪些已经 approved / rejected
-
-状态目录：`.athlete/team/requests/`
-
-### CoordinationPolicyStore
-
-回答：
-
-- 现在允不允许做 plan decision
-- 现在允不允许运行 shutdown request
-
-状态文件：`.athlete/team/policy.json`
-
-### BackgroundJobStore
-
-回答：
-
-- 哪些后台命令在跑
-- 谁发起的
-- 是否完成、失败、超时
-
-### WorktreeStore
-
-回答：
-
-- 哪些 worktree 存在
-- 绑定了哪个任务
-- 是否 active / kept / removed
-
-状态文件：
-
-- `.athlete/worktrees/index.json`
-- `.athlete/worktrees/events.jsonl`
-
-### MessageBus
-
-负责：
-
-- inbox 投递
-- 消息审计
-
-相关文件：
-
-- `.athlete/team/inbox/*.jsonl`
-- `.athlete/team/messages.jsonl`
-
-它不是最终业务真相源，但它是协作事件流和审计层。
-
-## 普通消息与正式协议的边界
-
-### 普通消息
-
-用于：
-
-- 通知
-- 提醒
-- 状态更新
-
-### 正式协议
-
-用于：
-
-- 会改变协作状态的沟通
-
-当前协议类型：
-
-- `plan_approval`
-- `shutdown`
-
-正式协议必须：
-
-- 有 `request_id`
-- 有 request / response 对应关系
-- 有持久化状态
-
-## 当前规则
-
-1. 新增状态前，先问是不是已有真相源应扩字段。
-2. 能复用现有真相源，就不要新造平行 JSON 文件。
-3. 任何需要跨 turn、跨 agent 保持一致的信息，都不能只存在 system prompt 里。
-4. 普通消息不能代替正式审批。

package/spec/architecture//350/277/220/350/241/214/346/227/266/345/276/252/347/216/257.md

@@ -1,82 +0,0 @@
-# 运行时循环
-
-## 当前 loop 在做什么
-
-当前主循环负责 5 件事：
-
-1. 组装 system prompt
-2. 注入运行时状态
-3. 调模型
-4. 执行工具
-5. 判断继续、yield、暂停、结束
-
-当前 lead 路径接法：
-
-- `runManagedAgentTurn`
-- `prepareLeadTurn`
-- `runAgentTurn`
-
-也就是说：
-
-- orchestrator 在 lead slice 开始前先做任务组织与派工
-- `runTurn` 继续专注模型请求、工具执行、continuation、verification、compact
-- teammate / subagent loop 不走 lead orchestrator
-
-## 当前最重要的机器规则
-
-### 计划规则
-
-变更型动作默认要求先 `todo_write`。
-
-### inbox 规则
-
-lead 和 teammate 的 inbox 在 turn 开头统一注入。
-
-### verification 规则
-
-发生文件改动或 mutating shell 后，会进入 verification 状态机。
-
-verification 不是无限提醒：
-
-- `pendingPaths` 会随 session 持久化，continuation 后仍然有效
-- 显式 build / test / verify 命令会记录为正式 verification attempt
-- 对轻量交付物（如 `validation/*.md`、`.txt`）的定向 `read_file` 检查，也会被记录为一次通过的轻量验证
-- 如果任务已经结束、输出文件已经存在且属于轻量交付物，finalize 会先尝试 auto-readback，再决定是否 pause 给用户
-
-### 收口规则
-
-当主目标已经满足时，runtime 会优先结束，而不是继续补做 task / todo / verification 文书动作。
-
-- 收口判断不只看模型文本，还看 `changedPaths`、`verificationState`、todo 完成度与本轮是否已有实质工具活动
-- 一旦进入“应该收口”的区间，`task_list` / `task_get` / `task_update` 会在工具集里被隐藏
-- 当 todo 已全部完成时，`todo_write` 也会在收口阶段从工具集中移除，避免重复 closeout
-- 旧 todo 过时但真实工作已完成时，不再把 stale todo 当成 finalize 的硬阻塞
-
-### continuation 规则
-
-工具步数过多时，不中断任务，而是自动续跑。
-
-### compact 规则
-
-上下文过长时，自动压缩请求上下文，不直接放弃任务。
-
-### 浏览器 workflow 规则
-
-在相关 skill 已加载且浏览器工具可用时：
-
-- 自然语言网页任务优先走 Playwright MCP 工具
-- shell 网页抓取只能作为 fallback
-- 在导航和 snapshot 之前，shell detour 会被 workflow guard 拦住
-
-### 交互等待反馈
-
-交互模式下，用户发出输入后、模型真正开始输出前，会显示短暂 spinner。
-
-它属于 UI 层，不参与 agent 状态机本身。
-
-## 设计要求
-
-1. loop 只保留全局调度规则。
-2. 具体模块细节下沉到各自目录。
-3. 新增长期能力时，优先接到 runtime state、tool priority 或 workflow guard，而不是直接堆 prompt。
-4. “应该结束”的判断必须落在机器层，不能只靠 prompt 提醒模型自觉收口。

package/spec/implementation/README.md

@@ -1,17 +0,0 @@
-# implementation
-
-这一组文档只回答一个问题：
-
-**Athlete 下一阶段应该先做什么。**
-
-## 当前优先级
-
-1. 保住耐跑底盘
-2. 增加总指挥层
-3. 标准化 skills 扩展口
-
-## 不在这一阶段优先级前排的事
-
-- 大规模自治 swarm
-- 跨项目人格记忆
-- 过早行业大而全

package/spec/implementation//346/250/241/345/235/227/347/272/247/345/274/200/345/217/221/344/273/273/345/212/241/345/215/225.md

@@ -1,55 +0,0 @@
-# 模块级开发任务单
-
-## Phase 1：保底
-
-### 目标
-
-在不破坏当前耐跑能力的前提下继续演进。
-
-### 任务
-
-1. 补强 continuation / compact / recovery 相关测试
-2. 把主循环继续瘦身，避免后续总指挥逻辑直接堆进去
-3. 明确当前 control plane 字段与职责
-
-## Phase 2：总指挥层
-
-### 目标
-
-让主 Agent 更会决定“什么时候该用哪一招”。
-
-### 任务
-
-1. 增加 orchestrator 目录与基础类型
-2. 定义任务拆分、派工、等待、收结果的最小流程
-3. 支持在 lead 层统一选择：
-   - 自己做
-   - 派 subagent
-   - 派 teammate
-   - 丢 background
-4. 增加 reviewer / verifier / planner 的边界设计
-
-## Phase 3：skills 标准化
-
-### 目标
-
-让 skills 成为稳定扩展口，而不是散装提示词。
-
-### 任务
-
-1. 定义 skill metadata 规范
-2. 定义 skill 的触发方式与加载方式
-3. 定义 skill 与角色、工具、任务的关系
-4. 补技能加载、缺技能、错技能的测试
-
-## Phase 4：再往外扩
-
-### 目标
-
-从 coding harness 扩到更广的复杂任务。
-
-### 任务
-
-1. 文档与表格类增强
-2. 浏览器 / 外部系统类能力
-3. 项目内经验沉淀

package/spec/implementation//347/233/256/345/275/225/347/273/223/346/236/204/345/210/260/344/273/243/347/240/201/346/226/207/344/273/266/346/230/240/345/260/204/350/241/250.md

@@ -1,101 +0,0 @@
-# 目录结构到代码文件映射表
-
-## 当前主要目录
-
-- `src/agent/`: 主循环、prompt、continuation、verification、closeout
-- `src/agent/checkpoint/`: checkpoint 归一化、推导、resume 输入、prompt block
-- `src/agent/runtimeMetrics/`: runtime metrics 累积与 runtime summary
-- `src/tools/`: 模型可见工具与 handler
-- `src/skills/`: skill schema、discovery、matching、loading、workflow guard
-- `src/mcp/`: MCP 总接入层
-- `src/mcp/playwright/`: Playwright MCP 配置、路径、artifact、调用归一化
-- `src/context/`: repo root、state root、AGENTS、skills、ignore 发现
-- `src/config/`: 配置读取、环境变量、runtime config、app paths
-- `src/tasks/`: 持久化 task 真相源
-- `src/team/`: teammate、消息、协议、policy
-- `src/background/`: 后台任务
-- `src/worktrees/`: 目录隔离
-- `src/subagent/`: 一次性子智能体
-- `src/interaction/`: 共享交互控制层与 shell 契约
-- `src/shell/cli/`: CLI shell 输入、输出、turn 展示、intro
-- `src/ui/`: CLI 文本格式化、runtime summary 和兼容导出
-- `src/telegram/`: Telegram 私聊通道、delivery、附件、CLI、process lock
-- `src/weixin/`: Weixin 私聊通道、OpeniLink client、delivery、context_token、CLI、process lock
-
-## 当前 lightweight context 对应代码
-
-- `src/agent/promptSections.ts`: static / dynamic prompt layer
-- `src/agent/toolResultStorage.ts`: externalized tool result 落盘
-- `src/agent/toolResultPreview.ts`: tool payload 预览与 transport 压缩
-- `src/tools/files/toolResultArtifact.ts`: `.athlete/tool-results/...` 的紧凑 artifact read
-- `src/agent/contextBuilder.ts`: 使用轻量 payload 的请求上下文构建
-
-## 当前 checkpoint / continuation 对应代码
-
-- `src/agent/checkpoint.ts`: checkpoint 对外导出面
-- `src/agent/checkpoint/base.ts`: checkpoint 默认结构与从 session 派生
-- `src/agent/checkpoint/state.ts`: checkpoint 归一化与生命周期更新
-- `src/agent/checkpoint/derivation.ts`: completedSteps / nextStep / artifact 推导
-- `src/agent/checkpoint/prompt.ts`: checkpoint 恢复输入与 prompt block
-- `src/agent/turnPersistence.ts`: turn 开始、yield、recovery、tool batch 的 session 持久化接线
-- `src/agent/managedTurn.ts`: continuation 输入通过 checkpoint 生成
-
-## 当前 runtime metrics / 仪表盘 对应代码
-
-- `src/agent/runtimeMetrics.ts`: runtime metrics 对外导出面
-- `src/agent/runtimeMetrics/state.ts`: `runtimeStats` 归一化与事件累积
-- `src/agent/runtimeMetrics/summary.ts`: session runtime summary 生成
-- `src/agent/api.ts`: provider request timing 与 provider usage 采集
-- `src/agent/runTurn.ts`: tool execution、compression、recovery 等运行事件统计接线
-- `src/ui/runtimeSummary.ts`: 交互态 runtime summary 文本格式化
-- `src/interaction/localCommands.ts`: 共享本地命令语义与 `/runtime` / `/stats` / `/仪表盘` 路由
-- `src/ui/localCommands.ts`: CLI 默认输出适配与兼容导出
-
-## 当前交互 shell 对应代码
-
-- `src/interaction/sessionDriver.ts`: 共享交互 session loop、multiline、interrupt、turn 生命周期
-- `src/interaction/shell.ts`: `InteractionShell` / `ShellInputPort` / `ShellOutputPort` / `InteractionTurnDisplay`
-- `src/shell/cli/readlineInput.ts`: CLI 输入适配
-- `src/shell/cli/output.ts`: CLI 文本输出适配
-- `src/shell/cli/turnDisplay.ts`: CLI spinner + stream renderer 适配
-- `src/shell/cli/intro.ts`: CLI banner 与 launch hints
-- `src/shell/cli/shell.ts`: CLI shell 组装
-- `src/ui/interactive.ts`: CLI 入口薄壳，组装 shell 并启动共享 driver
-
-## 当前 Playwright MCP 对应代码
-
-- `src/mcp/config.ts`: MCP 配置归一化
-- `src/mcp/playwright/config.ts`: Playwright MCP 配置归一化与 server args
-- `src/mcp/playwright/paths.ts`: `.athlete/playwright-mcp/` 路径约定
-- `src/mcp/playwright/artifacts.ts`: artifact 目录准备、迁移、生成配置
-- `src/mcp/playwright/invoke.ts`: relative filename 归一化
-- `src/mcp/stdioClient.ts`: 真实 stdio MCP client
-- `src/mcp/toolAdapter.ts`: MCP tool 适配进 Athlete registry
-- `src/tools/runtimeRegistry.ts`: runtime registry 组装 built-in tools 与 MCP tools
-
-## 当前 closeout / verification 对应代码
-
-- `src/agent/finalize.ts`: tool-less turn 的最终收口与 verification / pause 行为
-- `src/agent/closeout.ts`: closeout 阶段的工具过滤与 stale todo 容忍规则
-- `src/agent/verificationState.ts`: verification 真相源
-- `src/agent/verificationSignals.ts`: lightweight verification signals 与 auto-readback
-- `src/agent/runTurn.ts`: 调度这些规则，但不持有它们的内部实现细节
-
-## 当前文档 / 验证位置
-
-- `skills/web-research/SKILL.md`
-- `skills/browser-automation/SKILL.md`
-- `spec/modules/lightweight-context-runtime.md`
-- `spec/modules/session-resume-compact.md`
-- `spec/modules/runtime-metrics.md`
-- `tests/playwright-mcp.test.ts`
-- `tests/browser-tool-priority.test.ts`
-- `tests/playwright-workflow-guard.test.ts`
-- `tests/agent-closeout.test.ts`
-- `tests/runtime-lightweight-context.test.ts`
-- `tests/runtime-checkpoint-resume.test.ts`
-- `tests/runtime-observability.test.ts`
-- `scripts/verify-runtime-lightweight-context-api.mjs`
-- `scripts/verify-runtime-checkpoint-api.mjs`
-- `scripts/verify-runtime-observability-api.mjs`
-- `validation/`

package/spec/interfaces/InteractionShell.md

@@ -1,85 +0,0 @@
-# InteractionShell
-
-## 作用
-
-`InteractionShell` 是共享交互控制层和具体外壳之间的正式边界。
-
-它让 Athlete 的交互 session loop 可以复用同一个大脑，同时替换 CLI、桌面等不同壳。
-
-## 当前真实能力
-
-### 参与者
-
-- `InteractiveSessionDriver`: 共享交互控制器
-- `InteractionShell`: 壳总接口
-- `ShellInputPort`: 输入端口
-- `ShellOutputPort`: 输出端口
-- `InteractionTurnDisplay`: turn 展示端口
-
-### 当前契约语义
-
-#### `ShellInputPort`
-
-负责：
-
-- 读取普通输入
-- 读取 multiline 输入
-- 绑定 interrupt 事件
-
-不负责：
-
-- 决定 task / runtime 真相
-- 自己执行 agent turn
-
-#### `ShellOutputPort`
-
-负责：
-
-- 输出 `plain / info / warn / error / dim / heading / tool / interrupt`
-- 保持壳自己的展示风格
-
-不负责：
-
-- 修改 session 真相
-- 决定本地命令语义
-
-#### `InteractionTurnDisplay`
-
-负责：
-
-- 接收 turn 生命周期内的 `AgentCallbacks`
-- 展示流式 assistant / reasoning / tool 状态
-- 在 turn 结束或中断时 flush / dispose
-
-#### `InteractionShell`
-
-负责把上面三部分组装给共享 driver 使用。
-
-## 当前 CLI 实现
-
-- `src/shell/cli/readlineInput.ts`
-- `src/shell/cli/output.ts`
-- `src/shell/cli/turnDisplay.ts`
-- `src/shell/cli/shell.ts`
-
-CLI 当前通过这些适配器接入：
-
-- `readline`
-- `process.stdin` / `process.stdout`
-- `chalk`
-- spinner / stream renderer
-
-这些都必须留在 CLI shell 内，不进入共享 driver。
-
-## 规则
-
-1. `InteractiveSessionDriver` 不能依赖 `readline`、stdio、`chalk`。
-2. shell 只能提供输入、输出和 turn 展示适配，不能把控制面状态偷搬到壳里。
-3. 本地命令的语义应落在共享交互层，shell 只负责把结果显示出来。
-4. interrupt 的来源可以因壳不同而不同，但共享 driver 的 abort 语义必须一致。
-
-## 未来方向
-
-- 桌面壳可以实现自己的 `ShellInputPort`，例如输入框提交、多行编辑器、停止按钮。
-- 桌面壳可以实现自己的 `ShellOutputPort` / `InteractionTurnDisplay`，例如富文本消息区和状态面板。
-- 未来如果出现 web / mobile 壳，也应优先复用这组契约，而不是复制一套 session loop。

package/spec/interfaces/ProviderAdapter.md

@@ -1,23 +0,0 @@
-# ProviderAdapter
-
-## 作用
-
-ProviderAdapter 把 Athlete 的请求发送到具体模型服务，并返回统一结果。
-
-## 最小职责
-
-- 接收消息数组
-- 接收模型名
-- 接收工具定义
-- 返回 assistant 文本、reasoning、tool calls
-- 对常见 provider 错误提供可恢复语义
-
-## 不负责
-
-- 任务拆分
-- 控制面状态判断
-- 工具执行
-
-## 稳定边界
-
-只要 adapter 还能提供统一输出，底层 provider 可以继续替换。

package/spec/interfaces/README.md

@@ -1,17 +0,0 @@
-# 接口契约
-
-这一组文档不追求把所有 TypeScript 细节抄一遍。
-
-它们只说明 Athlete 内核最关键的抽象边界：
-
-- provider adapter
-- runtime loop
-- session store
-- tool registry
-- interaction shell
-
-## 使用规则
-
-1. 接口文档写稳定边界，不写瞬时实现细节。
-2. 新能力优先问“该落在哪个接口”，再问“该落在哪个文件”。
-3. 如果某个改动让接口职责明显变混，优先拆接口。

package/spec/interfaces/RuntimeLoop.md

@@ -1,28 +0,0 @@
-# RuntimeLoop
-
-## 作用
-
-RuntimeLoop 负责驱动一个 turn，直到：
-
-- 完成
-- 暂停
-- yield
-- 报错
-
-## 最小职责
-
-- 组装请求上下文
-- 读运行时状态
-- 调模型
-- 执行工具
-- 处理 continuation / compact / verification
-
-## 不负责
-
-- 保存长期任务真相
-- 发明新工具
-- 实现具体业务流程
-
-## 下一阶段要求
-
-总指挥层可以成为 loop 的上游决策来源，但不能把 RuntimeLoop 变成一个巨大的业务文件。

package/spec/interfaces/SessionStore.md

@@ -1,22 +0,0 @@
-# SessionStore
-
-## 作用
-
-SessionStore 负责保存和恢复任务现场。
-
-## 最小职责
-
-- 创建 session
-- 追加消息
-- 保存 todo / verification / taskState
-- 加载既有 session
-
-## 不负责
-
-- 任务板真相
-- teammate roster
-- worktree 生命周期
-
-## 关键要求
-
-session 恢复不能破坏 Athlete 的耐跑能力。

package/spec/interfaces/ToolRegistry.md

@@ -1,21 +0,0 @@
-# ToolRegistry
-
-## 作用
-
-ToolRegistry 负责统一管理模型可见工具。
-
-## 最小职责
-
-- 返回工具定义
-- 按名称执行工具
-- 根据 mode / runtime 过滤工具集
-
-## 不负责
-
-- provider 请求
-- session 存储
-- 任务真相维护
-
-## 关键要求
-
-无论未来 tools、skills、MCP 怎么扩，模型看到的动作入口都要保持统一。