@jun133/athlete 0.0.5 → 0.0.6

package/spec//347/224/250/346/210/267/345/256/241/351/230/205//347/263/273/347/273/237/345/205/250/346/231/257.md

@@ -0,0 +1,57 @@
+# 系统全景
+
+## 用一句人话说
+
+Athlete 是一个会自己持续推进任务、会拆解复杂工作、会把任务分给不同执行通道、并且能把整个过程记下来的智能体系统。
+
+## 它怎么工作
+
+你可以把它想成三层：
+
+### 1. 主 Agent
+
+这是总指挥。
+
+它负责：
+
+- 理解目标
+- 判断任务复杂度
+- 决定是自己做，还是拆给别的执行者
+- 跟踪当前进度、阻塞和合流点
+
+### 2. 控制面
+
+这是账本和现场。
+
+它负责记住：
+
+- 现在有哪些任务
+- 谁在做
+- 哪个任务被什么阻塞
+- 哪些后台任务仍在跑
+- 哪些 worktree 仍有效
+- 当前 session、checkpoint、runtime 状态到了哪一步
+
+### 3. 执行与通道
+
+这是手脚和外壳。
+
+它负责：
+
+- 读写文件
+- 跑命令
+- 下载文件
+- 调用外部能力
+- 通过 CLI、Telegram、Weixin 和未来其他宿主接收输入、回传结果
+
+## 为什么它不是单兵系统
+
+因为它已经在做这些事：
+
+- 让 lead 提前组织任务
+- 让 teammate 和 background 各自承担不同执行方式
+- 让 worktree 隔离并行改动
+- 让宿主共用同一条核心运行主路径
+- 让 skill 和外部能力通过统一扩展口进入系统
+
+这说明 Athlete 的主心骨已经不是“一个人自己拼命干”，而是“一个主 Agent 组织整个工作系统往前跑”。

package/spec//347/224/250/346/210/267/345/256/241/351/230/205//351/241/271/347/233/256/350/214/203/345/233/264.md

@@ -0,0 +1,59 @@
+# 项目范围
+
+## 当前已经在范围内
+
+### 耐跑底盘
+
+- session 作为任务现场
+- checkpoint 与 continuation
+- 上下文压缩
+- verification / acceptance / closeout
+- runtime stats 和可见 summary
+
+### 总指挥能力
+
+- 主 Agent 的任务预处理
+- 任务拆分与最小任务图
+- lead / teammate / background / subagent 路由
+- wait / merge / blocked / ready 的机器语义
+
+### 控制面
+
+- SQLite 控制面账本
+- 任务、队友、协议、后台、worktree 的正式真相源
+
+### 扩展与通道
+
+- tools
+- skills
+- MCP
+- CLI
+- Telegram 私聊
+- 微信私聊
+
+## 当前明确不在范围内
+
+- 面向大众的图形化编排平台
+- 复杂商业化 swarm 市场
+- 跨项目长期人格记忆
+- 为了热闹而默认开一堆 agent 并发
+- 没有控制面约束的自治军团
+
+## 下一阶段优先级
+
+当前阶段优先继续强化这些能力：
+
+1. 主 Agent 的总指挥层
+2. 复杂任务拆分、派工、等待与合流
+3. 更清晰的技能扩展口和宿主扩展口
+4. reviewer / verifier / planner 这类专门角色的演进边界
+5. 面向更多宿主的统一接入主路径
+
+## 范围判断规则
+
+如果一个新需求同时满足下面两条，就应该往后放：
+
+- 会削弱耐跑底盘
+- 不能明显增强总指挥能力、控制面能力或标准扩展口
+
+Athlete 当前优先做“更会组织、更会持续推进”，不是“看起来更像万能 AI”。

package/spec/adr/ADR-0001-/345/215/225/346/250/241/345/274/217/345/205/250/346/235/203/351/231/220.md

@@ -1,16 +0,0 @@
-# ADR-0001：默认 Agent 模式优先，保留 Read-Only 辅助模式
-
-## 背景
-
-Athlete 起家的核心能力是“在终端里持续把任务做完”，而不是只做分析。
-
-## 决策
-
-1. 默认心智模型以 `agent` 模式为主。
-2. `read-only` 保留，用于分析、审阅、低风险探索。
-3. 核心规格和扩展方向优先围绕 `agent` 模式设计。
-
-## 后果
-
-- Athlete 保持“能干活”的产品性格
-- 同时仍保留安全一些的分析入口

package/spec/adr/ADR-0002-/345/215/225agent/350/265/267/346/255/245/345/271/266/351/242/204/347/225/231/345/244/232agent/350/276/271/347/225/214.md

@@ -1,19 +0,0 @@
-# ADR-0002：强主 Agent 起步，预留多 Agent 边界
-
-## 背景
-
-Athlete 当前最强的价值来自耐跑主 Agent。
-
-同时，复杂任务又确实需要 subagent、teammate、background、worktree。
-
-## 决策
-
-1. 主 Agent 仍是系统核心。
-2. 多 Agent 是按需能力，不是默认军团模式。
-3. 下一阶段优先补“总指挥层”，不是先做大规模 swarm。
-
-## 后果
-
-- 能保住当前耐跑底盘
-- 以后还能继续扩到多 Agent
-- 不会过早进入复杂协作失控状态

package/spec/adr/ADR-0003-openai-compatible/344/274/230/345/205/210.md

@@ -1,16 +0,0 @@
-# ADR-0003：OpenAI-Compatible 优先
-
-## 背景
-
-Athlete 要做 harness，而不是绑死在某一家 provider 上。
-
-## 决策
-
-1. 当前 provider 接口优先兼容 OpenAI-compatible。
-2. provider 选择属于配置问题，不属于业务设计问题。
-3. 上层 runtime、tools、orchestrator 不依赖某一家的专属行为。
-
-## 后果
-
-- Athlete 更容易切换模型与服务商
-- 后续扩展更稳定

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

@@ -1,115 +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/`
-
-负责：
-
-- 向模型暴露动作
-- 参数解析
-- 机器约束检查
-- 调用底层能力
-- 统一治理 metadata、fail-closed 暴露过滤、routing hint 与 signal 校验
-
-### 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/`
-
-负责：
-
-- 复杂度判断
-- 最小任务图落盘
-- 从 task / team / background / worktree 真相源派生任务 lifecycle
-- self / subagent / teammate / background 路由
-- lead slice 开始前的任务组织
-
-## 当前最重要的架构边界
-
-### 控制面
-
-回答：
-
-- 现在有哪些任务
-- 谁该做、谁在做
-- 哪些正式协作在 pending
-- 哪些后台任务在跑
-- 哪些 worktree 仍然有效
-
-### 执行面
-
-回答：
-
-- 文件怎么改
-- 命令怎么跑
-- 浏览器怎么导航
-- 某个 worker 具体在执行什么
-
-### 关键规则
-
-1. 控制面不直接改文件。
-2. 执行面不发明控制面真相。
-3. orchestrator 负责调度，不负责具体文件改写。
-4. tools 提供动作，skills 提供 workflow，二者不互相替代。
-5. 主循环只做调度；closeout、verification signal、workflow gating 这类长期规则要下沉到独立模块。
-6. tool priority、browser-first、document routing、MCP fail-closed 之类策略属于机器层，不属于 prompt 路由表。
-7. task readiness、ownership、handoff legality、worktree binding reality 由机器从既有真相源派生，不靠 prompt 记忆。

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

@@ -1,120 +0,0 @@
-# 状态与真相源
-
-## 目标
-
-Athlete 要跑长任务、协作任务和恢复任务，关键状态不能只放在 prompt 里。
-
-必须有落盘真相源。
-
-## 当前真相源
-
-### TaskStore
-
-回答：
-
-- 有哪些任务
-- 哪些任务被阻塞
-- 谁被指派
-- 谁正在做
-- 任务绑定了哪个 worktree
-- orchestrator task 的 objective / kind / handoff metadata 是什么
-
-状态目录：`.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. 普通消息不能代替正式审批。
-5. task lifecycle 不是单独落盘的新 JSON；它由 `TaskStore` + `TeamStore` + `BackgroundJobStore` + `WorktreeStore` 的现有事实派生。
-6. handoff 缺失或冲突时必须 fail-closed，例如：缺失 teammate、缺失 background job、失效 worktree 绑定。

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

@@ -1,139 +0,0 @@
-# 运行时循环
-
-## 当前 loop 在做什么
-
-当前主循环负责 5 件事：
-
-1. 组装 system prompt
-2. 注入运行时状态
-3. 调模型
-4. 执行工具
-5. 判断继续、yield、暂停、结束
-
-当前 lead 路径接法：
-
-- `runManagedAgentTurn`
-- `prepareLeadTurn`
-- `runAgentTurn`
-
-也就是说：
-
-- orchestrator 在 lead slice 开始前先做任务组织与派工
-- 派工前先从 task / team / background / worktree 真相源派生任务 lifecycle
-- `runTurn` 继续专注模型请求、工具执行、continuation、verification、compact
-- teammate / subagent loop 不走 lead orchestrator
-
-当前 one-shot CLI 也走同一套 machine truth，只是终端外壳不同：
-
-- `src/cli.ts`
-- `src/cli/support.ts`
-
-one-shot 结束时必须把 terminal transition / verification / acceptance 收敛成稳定 closeout contract 输出。
-
-交互式 CLI 退出时还有一条独立规则：
-
-- 如果当前项目没有运行中的后台进程，`quit` 直接退出
-- 如果有运行中的后台进程，必须先列出它们，再由用户二选一：
-  - kill 全部后台进程并退出
-  - 取消退出继续运行
-- kill 不彻底时必须 fail-closed，不允许带着不可见孤儿进程假装退出成功
-
-## 当前最重要的机器规则
-
-### 计划规则
-
-变更型动作默认要求先 `todo_write`。
-
-### 任务编排规则
-
-lead 编排不再只看 task status 字段，而是看机器派生的 lifecycle：
-
-- `blocked`
-- `ready`
-- `active`
-- `completed`
-
-并同时判断：
-
-- runnableBy 是 lead / teammate / nobody
-- handoff 是否有合法控制面事实支撑
-- worktree 绑定是否仍然有效
-
-如果 teammate / background / worktree 的事实缺失或冲突，lead 路径会阻断新的派工，而不是继续默许推进。
-
-### 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 给用户
-- acceptance / verification 的跨生态判断统一经过 signal 层，不直接匹配某个 adapter 工具名
-
-### 收口规则
-
-当主目标已经满足时，runtime 会优先结束，而不是继续补做 task / todo / verification 文书动作。
-
-- 收口判断不只看模型文本，还看 `changedPaths`、`verificationState`、todo 完成度与本轮是否已有实质工具活动
-- 一旦进入“应该收口”的区间，`task_list` / `task_get` / `task_update` 会在工具集里被隐藏
-- 当 todo 已全部完成时，`todo_write` 也会在收口阶段从工具集中移除，避免重复 closeout
-- 旧 todo 过时但真实工作已完成时，不再把 stale todo 当成 finalize 的硬阻塞
-
-### continuation 规则
-
-工具步数过多时，不中断任务，而是自动续跑。
-
-### runtime transition 规则
-
-continue / recover / yield / pause / finalize 不再只靠零散布尔值和字符串拼接。
-
-- runtime 会产出结构化 transition：`action + reason code + detail`
-- `checkpoint.flow.lastTransition` 持久化最近一次关键 runtime 决策
-- `checkpoint.flow.reason` 只是从结构化 transition 派生的紧凑视图，不再是独立真相源
-- continuation / resume / recovery / closeout 都应优先读取这一层机器状态，而不是反推 prompt 文案
-
-### compact 规则
-
-上下文过长时，自动压缩请求上下文，不直接放弃任务。
-
-### 浏览器 workflow 规则
-
-在相关 skill 已加载且浏览器工具可用时：
-
-- 自然语言网页任务优先走 browser capability 工具
-- shell 网页抓取只能作为 fallback
-- 在导航和 snapshot 之前，shell detour 会被 workflow guard 拦住
-
-这里的“浏览器工具”可以由 Playwright MCP 提供，也可以由别的 adapter 提供；上层规则只认 browser capability / browser step。
-
-### 文档 workflow 规则
-
-当 file introspection 或 tool recovery 指向专用文档能力时：
-
-- 上层优先走 `document.read` / `spreadsheet.read` capability
-- 文档 phase 推进只认 `document_read_completed` signal
-- 不把 MinerU 名字继续塞进 acceptance / phase / route-change 主体
-
-### 交互等待反馈
-
-交互模式下，用户发出输入后、模型真正开始输出前，会显示短暂 spinner。
-
-它属于 UI 层，不参与 agent 状态机本身。
-
-## 设计要求
-
-1. loop 只保留全局调度规则。
-2. 具体模块细节下沉到各自目录。
-3. static system prompt 只承载高层 operating contract，不重复 machine-enforced 的 workflow / verification / closeout 细则。
-4. 新增长期能力时，优先接到 runtime state、tool priority 或 workflow guard，而不是直接堆 prompt。
-5. “应该结束”的判断必须落在机器层，不能只靠 prompt 提醒模型自觉收口。
-6. runtime 的关键转移原因必须可持久化、可测试、可区分，不能只留在 status 文本里。
-7. lead orchestrator 只消费 task lifecycle 这种派生控制面事实，不新增平行 orchestration 真相源。
-8. provider / browser / document 的生态差异可以停留在 adapter 层，但不能上浮成主循环规则。

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. 项目内经验沉淀