@jun133/athlete 0.0.4 → 0.0.6

package/spec//347/224/250/346/210/267/345/256/241/351/230/205//345/256/252/346/263/225/345/216/237/345/210/231/17-/346/211/251/345/261/225/351/235/240/344/272/213/344/273/266/347/224/237/351/225/277.md

@@ -0,0 +1,71 @@
+# 17-扩展靠事件生长
+
+## 原则
+
+扩展不能只靠往 system prompt 里继续堆规则。
+
+系统要通过清晰的扩展口、运行时事件点和生命周期边界来生长。
+
+## 为什么
+
+Athlete 现在已经不是一个单兵型 Agent。
+
+它后面还会继续长出：
+
+- 更多技能
+- 更多工具
+- 更多角色
+- 更多宿主
+- 更多运行时通知和可见事件
+
+如果没有正式扩展点，最后会出现三种坏事：
+
+1. 主循环越来越胖
+2. 宿主越来越会偷偷拼 runtime
+3. 新能力只能靠 prompt 和胶水代码硬塞进去
+
+## 在 Athlete 里的含义
+
+Athlete 当前正式扩展口至少有四类：
+
+1. 工具扩展
+   - tool registry
+   - governed tool metadata
+2. 技能扩展
+   - skill catalog
+   - skill matching / loading
+3. 外部能力扩展
+   - MCP
+4. 运行时与宿主扩展
+   - runtime callbacks
+   - turn visible events
+   - lifecycle closeout
+   - host extra tools
+   - host identity
+
+也就是说，Athlete 现在已经不只需要“tool / skill / MCP”三个扩展口。
+
+它还必须明确：
+
+- turn 开始点
+- turn 执行点
+- pause / abort / error / finalize 收口点
+- visible event 输出点
+- 宿主注入 extra tool 的边界
+
+这些 runtime / lifecycle 点，必须是正式边界，不是散装胶水。
+
+## 当前对应
+
+- `src/tools/runtimeRegistry.ts`
+- `src/skills/`
+- `src/mcp/`
+- `src/host/`
+- `src/chat/`
+- `src/ui/`
+
+## 当前要求
+
+1. 新扩展优先长在正式扩展口，不优先长在 prompt 里。
+2. 宿主扩展必须走 `src/host/`，不能绕进核心内部模块。
+3. runtime 事件和生命周期收口要作为正式设计对象，而不是“以后再补”。

package/spec//347/224/250/346/210/267/345/256/241/351/230/205//345/256/252/346/263/225/345/216/237/345/210/231/18-/344/270/273/345/276/252/347/216/257/345/222/214/346/226/207/344/273/266/351/203/275/344/270/215/350/203/275/351/225/277/350/203/226.md

@@ -0,0 +1,37 @@
+# P18 主循环和文件都不能长胖
+
+## 原则
+
+主循环必须保持调度中心地位；单个文件必须保持单一职责；系统靠解耦和模块组合生长，而不是靠把越来越多逻辑塞进一个文件。
+
+## 为什么
+
+如果一个文件什么都做：
+
+- AI 很容易改坏别的部分
+- 人很难知道该去哪里改
+- 小改动会牵动全身
+- 后续维护成本会迅速失控
+
+Athlete 要的是可持续迭代，不是短期堆代码。
+
+## 铁律
+
+1. 单文件单职责优先，解耦优先，模块化优先。
+2. “先能跑再塞进一个文件”不是长期方案，发现职责混杂就要拆。
+3. 行数阈值只是预警，不是宗教；真正要盯的是职责是否混杂、边界是否清楚、后续是否好维护。
+4. 主循环只保留全局调度规则，不吞模块细节。
+5. 新功能优先长在新模块、新目录或明确扩展点上，不优先堆进已有大文件。
+
+## 在 Athlete 当前阶段的含义
+
+- 一个文件如果已经承担两件以上主要事情，就优先拆。
+- 能拆成状态层、执行层、验证层、展示层，就不要继续糊在一起。
+- 能删掉错误旧层，就不要为了兼容继续保留。
+
+## 当前对应
+
+- `src/agent/runTurn.ts`
+- `src/tools/`
+- `src/team/`
+- `src/tasks/`

package/spec//347/224/250/346/210/267/345/256/241/351/230/205//345/256/252/346/263/225/345/216/237/345/210/231/20-/345/244/226/351/203/250/344/272/213/345/256/236/345/277/205/351/241/273/347/273/221/345/256/232/350/257/201/346/215/256.md

@@ -0,0 +1,48 @@
+# P20 外部事实必须绑定证据
+
+## 原则
+
+任何来自网页、文档、邮件、截图、检索结果或外部文件的事实，只要要进入结构化产物、摘要、报告或最终结论，就必须绑定证据。
+
+## 为什么
+
+如果系统允许“查到一点点，再补写一整段”：
+
+- 结果会看起来很完整，但并不可靠
+- 模型会把猜测混进事实
+- 人很难区分“真实抓到的”与“模型补出来的”
+
+Athlete 要做的是可执行系统，不是会写漂亮答案的壳。
+
+## 在 Athlete 里的含义
+
+进入最终产物的每条外部事实，至少应能追到：
+
+- 来源名
+- 来源链接或来源文件
+- 抓取时间
+- 证据摘录或定位信息
+
+如果没有这些，系统应优先：
+
+- 继续抓取
+- 标成未证实
+- 或直接拒绝写入最终结果
+
+而不是让模型自行补齐。
+
+如果任务本身还声明了结构化证据字段，例如：
+
+- `source_name`
+- `link`
+- `fetched_at`
+- `evidence_excerpt`
+
+那这些字段也属于硬门禁。缺任一项，都不能算“证据已绑定”。
+
+## 当前对应
+
+- `src/agent/prompt/`
+- `src/tools/files/toolResultArtifact.ts`
+- `src/agent/verification.ts`
+- `spec/技术实现/主循环与调度.md`

package/spec//347/224/250/346/210/267/345/256/241/351/230/205//345/256/252/346/263/225/345/216/237/345/210/231/21-/346/262/241/351/252/214/350/277/207/345/260/261/344/270/215/350/203/275/346/224/266/345/217/243.md

@@ -0,0 +1,46 @@
+# P21 没验过就不能收口
+
+## 原则
+
+没有真实验证通过，就不能把任务判定为完成。
+
+## 为什么
+
+“写了文件”不等于“做成了”。
+
+如果系统允许下面这些情况直接收口：
+
+- 服务没启动
+- 页面没打开
+- JSON 不可解析
+- 关键文件缺失
+- 结果文件内容不可读
+
+那最后交付出来的就只是看起来像完成。
+
+## 在 Athlete 里的含义
+
+closeout 必须依赖真实验收条件，而不是模型自述。
+
+至少要检查：
+
+- 任务要求的关键文件是否存在
+- 关键命令是否实际跑通
+- 关键接口或页面是否真实可用
+- verification state 是否与真实产物一致
+
+如果任务已经显式给出了 acceptance / closeout 契约，还必须继续检查：
+
+- 必需文件是否齐全
+- JSON 是否可解析
+- 研究 / 文档结果里的证据字段是否齐全
+- API / 页面探活结果是否真的通过
+
+只要关键验证没过，就继续工作，不允许 finalize。
+
+## 当前对应
+
+- `src/agent/turn/finalize.ts`
+- `src/agent/turn/closeout.ts`
+- `src/agent/verification.ts`
+- `spec/技术实现/主循环与调度.md`

package/spec//347/224/250/346/210/267/345/256/241/351/230/205//345/256/252/346/263/225/345/216/237/345/210/231/22-/351/230/266/346/256/265/346/216/250/350/277/233/345/277/205/351/241/273/346/234/211/346/234/272/345/231/250/347/212/266/346/200/201.md

@@ -0,0 +1,40 @@
+# P22 阶段推进必须有机器状态
+
+## 原则
+
+任务处于哪个阶段，不应只靠模型口头描述，必须有机器可读的阶段状态。
+
+## 为什么
+
+长任务最容易出现两种漂移：
+
+- 还没完成当前阶段，就提前说“下一步”
+- 已经卡住了，但还在原地重复动作
+
+如果没有显式阶段，系统就无法判断自己是在推进、卡住，还是绕圈。
+
+## 在 Athlete 里的含义
+
+像下面这类任务，都应有清楚 phase：
+
+- 研究任务：发现来源 -> 抓取 -> 归一化 -> 落地 -> 验证
+- 文档任务：找文档 -> 获取文档 -> 读取 -> 抽取结构 -> 证据映射 -> 验证
+- 编码任务：搭结构 -> 实现 -> 安装依赖 -> 运行 -> 验证 -> 收口
+
+阶段切换应尽量由真实事件触发：
+
+- 找到文档
+- 读到文档
+- 生成了结构化结果
+- 验证通过
+
+而不是只因为模型说“现在进入下一步”。
+
+如果同一 phase 连续多轮没有新增成果，机器状态还必须明确记住“正在停滞”，并推动系统换路、恢复或进入更明确的补救分支。
+
+## 当前对应
+
+- `src/agent/checkpoint/`
+- `src/agent/runtimeTransition/`
+- `src/agent/session/taskState.ts`
+- `spec/技术实现/状态与真相源.md`

package/spec//347/224/250/346/210/267/345/256/241/351/230/205//345/256/252/346/263/225/345/216/237/345/210/231/23-/346/226/207/346/234/254/351/223/276/350/267/257/345/277/205/351/241/273/347/250/263/345/256/232/345/217/257/350/257/273.md

@@ -0,0 +1,38 @@
+# P23 文本链路必须稳定可读
+
+## 原则
+
+输入、日志、可见预览、持久化内容和生成文件，必须保持稳定、可读、可逆的文本链路。
+
+## 为什么
+
+一旦文本链路坏掉：
+
+- prompt 会被污染
+- 模型会误解任务
+- 日志会失去诊断价值
+- 生成文件会直接变坏
+
+这不是界面小问题，而是正确性问题。
+
+## 在 Athlete 里的含义
+
+系统必须把编码和文本完整性当作主链路要求，而不是显示细节。
+
+至少应保证：
+
+- 中文和英文输入不被破坏
+- 可见日志和 tool preview 可读
+- session / checkpoint / artifacts 落盘后可再次读取
+- 写出的文本文件不出现乱码污染
+- shell / 子进程输出不能依赖平台默认编码碰运气
+- UTF-8 / UTF-16 等常见文本格式要能稳定识别，不误判成 binary
+
+如果出现乱码，优先级应高于继续堆功能。
+
+## 当前对应
+
+- `src/utils/stdio.ts`
+- `src/ui/streamRenderer.ts`
+- `src/agent/session/`
+- `src/tools/files/`

package/spec//347/224/250/346/210/267/345/256/241/351/230/205//345/256/252/346/263/225/345/216/237/345/210/231/24-/351/224/231/350/257/257/345/205/274/345/256/271/344/270/215/350/203/275/351/253/230/344/272/216/346/255/243/347/241/256/346/200/247.md

@@ -0,0 +1,38 @@
+# P24 错误兼容不能高于正确性
+
+## 原则
+
+错误旧逻辑、错误旧测试、错误旧兼容，不能为了“少改一点”而继续保留。
+
+## 为什么
+
+Athlete 还在高频演进阶段。
+
+如果系统已经确认某条旧行为是错的，却还继续兼容它：
+
+- 主链会越来越脏
+- 新规则会一直被旧规则拖住
+- 模型和运行时会同时背两套相互冲突的东西
+
+这会让系统越来越难修，而不是更稳定。
+
+## 在 Athlete 里的含义
+
+当旧逻辑与正确主干冲突时，优先顺序应是：
+
+1. 保正确
+2. 保简单
+3. 保唯一真相源
+4. 最后才考虑兼容
+
+如果旧测试在保护错误行为，就删除或重写。
+如果旧兼容层在阻碍主链修复，就删掉。
+不为错误行为保活。
+Athlete 还是新项目，不要求为错误历史写长期兼容分支。
+
+## 当前对应
+
+- `spec/`
+- `tests/`
+- `src/agent/`
+- `src/tools/`

package/spec//347/224/250/346/210/267/345/256/241/351/230/205//345/256/252/346/263/225/345/216/237/345/210/231/25-/346/226/260/351/241/271/347/233/256/344/270/215/344/270/272/346/227/247/346/256/213/344/275/231/344/277/235/346/264/273.md

@@ -0,0 +1,66 @@
+# P25 新项目不为旧残余保活
+
+## 原则
+
+Athlete 仍处于新项目高频演进阶段。
+
+对已经确认错误、过时、残余、阻碍主干的旧结构，不做长期兼容，不做保活，不做双轨并存。
+
+需要删就删，需要清就清。
+
+## 为什么
+
+新项目最怕的，不是改动大，而是：
+
+- 明知旧结构错了还继续背着走
+- 为了少改一点，把错误历史变成永久负担
+- 让主干长期同时维护“旧方式”和“新方式”
+
+这样做的结果通常不是更稳定，而是：
+
+- 主链变脏
+- 边界变糊
+- AI 和人都更难判断真实结构
+- 每一轮重构都要先向后看，无法以当前最优架构推进
+
+## 铁律
+
+1. 新项目优先当前正确主干，不优先旧兼容。
+2. 对错误旧逻辑、错误旧测试、错误旧文件、错误旧状态，不保活。
+3. 对阻碍主干的残余层、过渡层、平行层、双写层，优先删除。
+4. 除非有非常明确且必要的用户数据保留价值，否则不为了旧状态写长期兼容逻辑。
+5. 可以做一次性清理、一次性重建、一次性迁移；不要做永久兼容。
+6. “用户也许还会用到”不是保留错误残余的充分理由。
+7. 文档必须明确告诉维护者：哪些旧东西已经废弃，哪些要删，哪些不能再依赖。
+
+## 在 Athlete 当前阶段的含义
+
+- 如果旧 JSON 真相源已经阻碍 SQLite 账本，就下线旧真相源，不为它保留长期双写。
+- 如果旧调度路径已经与新调度模型冲突，就删掉旧路径，不让两套规则长期并存。
+- 如果旧测试保护的是错误结构，就删除或重写，不让错误测试绑架主干。
+- 如果旧宿主接线方式已经妨碍 host/core 分层，就重接或删除，不做历史包袱保留。
+
+## 允许做的事
+
+- 明确清理旧状态目录
+- 明确重建本地开发状态
+- 明确替换旧结构
+- 明确写废弃说明
+- 明确删除错误残余文件或路径
+
+## 不允许做的事
+
+- 为错误旧结构新增长期兼容层
+- 为了“看起来平滑”而保留平行真相源
+- 为了少改测试而继续保留错误行为
+- 为了照顾旧实现而放弃当前更优架构
+
+## 当前对应
+
+- `spec/`
+- `tests/`
+- `src/tasks/`
+- `src/team/`
+- `src/background/`
+- `src/worktrees/`
+- `src/orchestrator/`

package/spec//347/224/250/346/210/267/345/256/241/351/230/205//345/256/252/346/263/225/345/216/237/345/210/231/README.md

@@ -0,0 +1,37 @@
+# 宪法原则
+
+这一组文档是给人类审阅项目方向用的根本原则。
+
+它们回答的不是“某个模块怎么写”，而是：
+
+- 这个项目为什么要这样长
+- 哪些边界不能被实现细节反推翻
+- 当代码、测试和文档冲突时，应该先保护什么
+
+## 现在怎么读
+
+### 01 到 16
+
+这部分是当前已经稳定成立的底层原则：
+
+- 单智能体主循环
+- 工具处理器边界
+- 计划、知识、上下文、任务图
+- 后台、队友、协议、工作区
+- session、provider、配置
+
+### 17 到 25
+
+这部分是当前工程已经必须正面处理的系统原则：
+
+- 扩展口怎么长
+- 主循环和文件怎么保持清醒
+- 失败测试、验证、证据、机器状态
+- 文本链路、错误兼容、旧残余清理
+
+## 使用规则
+
+1. 宪法原则只写长期有效、能跨多个模块成立的规则。
+2. 一次性实现技巧不要升格成宪法。
+3. 模块细节、接口细节和仓库流程写去 `技术实现/`。
+4. 当产品定位发生变化时，要先检查这里是否需要更新。

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 更容易切换模型与服务商
-- 后续扩展更稳定