@jun133/athlete 0.0.4 → 0.0.6

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/276/256/344/277/241/347/247/201/350/201/212.md

@@ -0,0 +1,33 @@
+# 微信私聊
+
+## 当前定位
+
+微信是 Athlete 的另一个私聊宿主。
+
+它当前走 OpenILink 接入，并通过统一宿主边界进入核心。
+
+## 当前能力
+
+- `weixin login`
+- `weixin serve`
+- `weixin logout`
+- 私聊白名单
+- `context_token`
+- `/stop`
+- image / video / file / voice 输入
+- 文件与长回复回传
+
+## 当前关键实现
+
+- `src/weixin/cli.ts`
+- `src/weixin/service.ts`
+- `src/weixin/turnRunner.ts`
+- `src/weixin/sendFileTool.ts`
+- `src/weixin/deliveryQueue.ts`
+- `src/weixin/contextTokenStore.ts`
+
+## 当前约束
+
+1. 微信 turn 必须经 `src/host/`。
+2. 微信当前是 private only，不是 group 宿主。
+3. `context_token` 只服务通道投递，不是任务真相源。

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//346/211/251/345/261/225/346/234/272/345/210/266.md

@@ -0,0 +1,179 @@
+# 扩展机制
+
+## 当前正式扩展口
+
+1. tools
+2. skills
+3. MCP
+4. host runtime callbacks / extra tools
+
+## 当前正式分层
+
+### 1. tool action 层
+
+目录：
+
+- `src/tools/builtinCatalog.ts`
+- `src/tools/registry.ts`
+- `src/tools/runtimeRegistry.ts`
+- `src/tools/governance.ts`
+
+职责：
+
+- builtin tool 的正式注册
+- runtime tool source 的统一汇合
+- governance 校验
+- runtime exposure 排序与暴露
+
+规则：
+
+- tool 只负责动作，不负责 workflow。
+- 新 builtin tool 的正式接入点是 `src/tools/builtinCatalog.ts` 的单个 descriptor。
+- 所有 tool source 都必须先变成 `ToolRegistrySource`，再进入 registry。
+- registry 必须在暴露前做重复名冲突检测与 governance 校验。
+
+### 2. skill workflow 层
+
+目录：
+
+- `src/skills/discovery.ts`
+- `src/skills/schema.ts`
+- `src/skills/matching.ts`
+- `src/skills/state.ts`
+- `src/tools/skills/loadSkillTool.ts`
+
+职责：
+
+- 发现 skill
+- 声明 workflow 触发条件
+- 按需加载 skill 正文
+- 在 runtime 中阻止“该先 load_skill 却直接执行 workflow”
+
+规则：
+
+- skill 负责 workflow / 组织已有能力，不负责直接动作执行。
+- skill 正文不能绕过 tool registry 单独长出动作入口。
+- skill 只通过 `load_skill` 进入当前 turn，上下文层只放轻量 runtime hint，不回退成 catalog dump。
+
+### 3. MCP 外部能力层
+
+目录：
+
+- `src/mcp/clientManager.ts`
+- `src/mcp/toolAdapter.ts`
+- `src/mcp/registryIntegration.ts`
+
+职责：
+
+- 连接外部 server
+- 把发现到的 MCP tool 翻译成 Athlete 的正式 tool source
+- 补上 MCP 来源与 governance 元数据
+
+规则：
+
+- MCP 负责外部能力源，不直接改 builtin registry。
+- 正式主路径是：
+  `MCP discovery -> toolAdapter -> ToolRegistrySource(kind=mcp) -> createRuntimeToolRegistry(...) -> governance -> exposure`
+- MCP tool 不能绕过 shared registry / governance / exposure。
+
+### 4. host 注入层
+
+目录：
+
+- `src/host/toolRegistry.ts`
+- `src/telegram/sendFileTool.ts`
+- `src/weixin/sendFileTool.ts`
+
+职责：
+
+- 把宿主 extra tool 收口成正式 host source
+- 让宿主注入仍然经过 shared registry / governance / exposure
+
+规则：
+
+- host 负责宿主注入点，不负责平台内核路由规则。
+- host extra tool 不能伪装成 builtin。
+- 正式主路径是：
+  `host extra tool -> createHostToolRegistry(...) -> ToolRegistrySource(kind=host) -> createRuntimeToolRegistry(...) -> governance -> exposure`
+
+## 当前共享平台边界
+
+### registry
+
+- `ToolRegistrySource` 是正式扩展源模型。
+- source 负责回答“能力从哪来”，不负责执行细节。
+
+### governance
+
+- `src/tools/governance.ts` 只负责规范化、校验和 fail-closed。
+- 缺治理元数据、重复注册、违规结果信号，都必须在这里或 registry 边界显式失败。
+
+### runtime exposure
+
+- `src/tools/registry.ts` 负责把 builtin / MCP / host source 汇总成统一 runtime tool surface。
+- 排序、去冲突、最终 definitions/entries 暴露都在这一层完成。
+
+### host injection
+
+- `src/host/toolRegistry.ts` 只是宿主到 shared registry 的正式桥。
+- 宿主不能自己再造平行 runtime tool 池。
+
+## 当前已落地的关键能力
+
+- `mineru-pdf-reading`
+- `mineru-image-reading`
+- `mineru-doc-reading`
+- `mineru-ppt-reading`
+- `mineru_pdf_read`
+- `mineru_image_read`
+- `mineru_doc_read`
+- `mineru_ppt_read`
+- `web-research`
+- `browser-automation`
+- Telegram / 微信 send file tool 注入
+
+## 新能力的最短正式路径
+
+### 新增 builtin tool
+
+1. 写一个 tool handler 文件
+2. 在 `src/tools/builtinCatalog.ts` 增加一个 descriptor
+
+descriptor 必须同时声明：
+
+- tool implementation
+- 暴露 mode
+- governance
+
+### 新增 skill
+
+1. 增加 `SKILL.md`
+2. 让 skill metadata 声明 workflow 触发条件
+
+skill 不新增动作入口；动作仍走已有 tool。
+
+### 新增 MCP 能力
+
+1. 让 server 被 config / discovery 发现
+2. 让 `toolAdapter` 把它翻译成 governed MCP tool
+3. 让 `registryIntegration` 把它挂成 MCP source
+
+### 新增 host extra tool
+
+1. 写宿主 tool
+2. 声明 governance
+3. 只通过 `src/host/toolRegistry.ts` 注入
+
+## 当前清掉的临时接线
+
+- 不再以 `includeTools` 这种扁平拼接参数作为主路径扩展口。
+- 不再以“先摊平成 RegisteredTool 列表再猜来源”的方式表示 MCP。
+- host send-file tool 不再挂在 builtin governance 目录里假装自己是内建能力。
+
+## 当前硬约束
+
+1. 不把扩展继续塞回 system prompt。
+2. tool / skill / MCP / host 必须通过正式扩展口接入。
+3. 宿主 extra tool 必须经 `src/host/` 注入。
+4. 同名 tool 注册必须在 registry 边界显式失败，不允许静默覆盖。
+5. 缺 governance 的扩展必须 fail-closed，不允许静默放行。

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//346/216/247/345/210/266/351/235/242/350/264/246/346/234/254.md

@@ -0,0 +1,32 @@
+# 控制面账本
+
+## 当前定位
+
+控制面账本是 Athlete 的正式本地裁决层。
+
+它负责回答：
+
+- 有哪些任务
+- 谁在做
+- 哪些协议还在 pending
+- 哪些后台任务在跑
+- 哪些 worktree 有效
+
+## 当前实现
+
+- `src/control/ledger/open.ts`
+- `src/control/ledger/migrations.ts`
+- `src/control/ledger/taskRepo.ts`
+- `src/control/ledger/teamRepo.ts`
+- `src/control/ledger/requestRepo.ts`
+- `src/control/ledger/policyRepo.ts`
+- `src/control/ledger/backgroundRepo.ts`
+- `src/control/ledger/worktreeRepo.ts`
+
+## 当前要求
+
+1. 新的控制面状态优先进入 SQLite，不再优先发明 JSON 文件。
+2. 旧 JSON 真相如果妨碍主干，应直接清理。
+3. 宿主层和展示层不能成为控制面真相。
+4. session 现场负责单个任务现场；控制面账本负责跨任务裁决、协作、execution、worktree。
+5. 如果 session 和 ledger 同时声称能裁决同一件事，说明边界错了，要继续收敛，不做双裁决。

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//351/205/215/347/275/256/347/263/273/347/273/237.md

@@ -0,0 +1,31 @@
+# 配置系统
+
+## 当前入口
+
+- `src/config/store.ts`
+
+## 当前职责
+
+- 读取全局 `config.json`
+- 读取项目 `.athlete/.env`
+- 合并环境变量覆盖
+- 产出统一 runtime config
+
+## 当前内部结构
+
+- `src/config/store.ts`
+  - 对外唯一入口
+- `src/config/fileStore.ts`
+  - 只负责 config file 持久化和 schema 升级
+- `src/config/runtime.ts`
+  - 只负责 runtime 合并和宿主所需归一化
+- `src/config/env.ts`
+  - 只负责 `.env` 装载
+
+## 当前必须守住的事
+
+1. 配置入口只能有一个。
+2. 全局配置要有 schema version。
+3. 旧配置只允许一次性升级，不做长期脏兼容。
+4. Telegram、微信、MCP、provider 都必须从这里出 runtime config。
+5. 宿主、CLI、tool、service 不能各自再偷偷读 `.env` 造第二入口。

package/spec//346/212/200/346/234/257/345/256/236/347/216/260//346/200/273/344/275/223/346/236/266/346/236/204.md

@@ -0,0 +1,115 @@
+# 总体架构
+
+## 一句话
+
+Athlete 当前是一套“耐跑主 Agent + 总指挥调度 + 统一控制面 + 多宿主外壳”的系统。
+
+## 当前正式分层
+
+### 1. 核心执行系统
+
+目录：
+
+- `src/agent/`
+- `src/orchestrator/`
+- `src/tools/`
+- `src/mcp/`
+- `src/skills/`
+- `src/context/`
+- `src/config/`
+- `src/control/ledger/`
+- `src/tasks/`
+- `src/team/`
+- `src/execution/`
+- `src/worktrees/`
+- `src/changes/`
+
+职责：
+
+- turn 执行
+- 主 Agent 预处理
+- 任务拆分与调度
+- tool / skill / MCP 接线
+- session / checkpoint / verification / acceptance / runtime stats
+- 控制面真相源
+
+### 2. 宿主运行边界
+
+目录：
+
+- `src/host/`
+
+职责：
+
+- 共享 session 入口
+- 共享 turn 入口
+- 共享 runtime tool registry 入口
+- 共享 pause / abort / error / closeout 收口
+- 宿主扩展点
+
+### 3. 宿主适配层
+
+目录：
+
+- `src/cli/`
+- `src/interaction/`
+- `src/ui/`
+- `src/shell/cli/`
+- `src/telegram/`
+- `src/weixin/`
+
+职责：
+
+- 输入输出
+- transport
+- 展示
+- typing / visible / delivery
+- stop 语义
+- commander 和本地命令
+
+规则：
+
+- 宿主只做壳，不定义 runtime 真相。
+- 真正执行 turn 时，宿主必须统一经过 `src/host/`。
+
+## 当前系统主轴
+
+Athlete 的主轴不是“让一个 Agent 什么都亲自做”，而是：
+
+1. lead 先理解和组织任务
+2. 控制面把任务状态落盘
+3. orchestrator 判断下一步由谁来做
+4. 执行者完成后再回到 lead 合流
+5. 宿主只负责把这套主路径接给不同通道
+
+## 当前关键边界
+
+### 主 Agent 回答
+
+- 当前任务是什么
+- 现在该继续、拆分、派工还是等待
+
+### 控制面回答
+
+- 谁在做
+- 哪些任务 blocked
+- 哪些后台任务和 worktree 仍有效
+
+### 宿主边界回答
+
+- 一个宿主怎样进入核心
+- 它怎样注入 extra tool / callbacks
+- 它怎样统一处理 pause / abort / error
+
+### 宿主适配层回答
+
+- 消息从哪来
+- 输出到哪去
+- 这个宿主的可见语义是什么
+
+## 当前架构约束
+
+1. 控制面真相不允许从宿主层反推。
+2. 宿主不允许直接散连 `src/agent/turn.ts` 或 `src/tools/runtimeRegistry.ts`。
+3. 调度规则应长在 orchestrator，不应散落在各宿主。
+4. tools、skills、MCP、host 扩展都必须通过正式边界生长。

package/spec//346/212/200/346/234/257/345/256/236/347/216/260//347/212/266/346/200/201/344/270/216/347/234/237/347/233/270/346/272/220.md

@@ -0,0 +1,129 @@
+# 状态与真相源
+
+## 规则
+
+Athlete 当前只有一套正式真相源，不允许宿主、提示词或临时 JSON 再发明平行状态。
+
+## 当前正式真相源
+
+### 1. session 现场
+
+介质：
+
+- `paths.sessionsDir/*.json`
+
+正式格式：
+
+- 每个 session snapshot 都带 `schemaVersion`
+- 读取边界必须先过 `src/agent/session/snapshot.ts`
+- 版本不支持、JSON 损坏、关键字段损坏都在这里 fail closed
+
+核心内容：
+
+- canonical：
+  - `messages`
+  - `createdAt / updatedAt / cwd / title`
+- persisted machine state：
+  - `todoItems`
+  - `taskState`
+  - `checkpoint`
+  - `verificationState`
+  - `acceptanceState`
+  - `runtimeStats`
+- 明确不在这里落盘的东西：
+  - prompt diagnostics
+  - visible event cache
+  - host return facade
+
+对应实现：
+
+- `src/agent/session/`
+- `src/agent/checkpoint.ts`
+- `src/agent/runtimeMetrics.ts`
+- `src/agent/verification/`
+- `src/agent/acceptance/`
+
+### 2. 控制面账本
+
+介质：
+
+- `.athlete/control-plane.sqlite`
+
+核心内容：
+
+- task
+- team member
+- protocol request
+- coordination policy
+- execution
+- worktree
+
+对应实现：
+
+- `src/control/ledger/`
+- `src/tasks/`
+- `src/team/`
+- `src/execution/`
+- `src/worktrees/`
+
+### 3. 统一配置入口
+
+入口：
+
+- `src/config/store.ts`
+
+负责：
+
+- 全局配置文件
+- 项目 `.athlete/.env`
+- 环境变量覆盖
+- Telegram / 微信 / MCP / provider runtime config
+
+内部正式分层：
+
+- `src/config/fileStore.ts`
+  - 只负责 `config.json` 读写、schema version、一次性升级
+- `src/config/runtime.ts`
+  - 只负责 `.env + env + file config` 合并成 runtime config
+- 但对外仍然只有 `src/config/store.ts`
+
+### 4. 宿主绑定状态
+
+宿主可以持久化自己的绑定和游标，但这些不是控制面裁决源。
+
+例如：
+
+- Telegram session map / offset
+- 微信 session map / sync buf / context_token / delivery queue
+
+它们只负责通道运行，不负责定义任务和调度真相。
+
+额外约束：
+
+- host binding 只能指向正式 session id
+- session 缺失时可以显式新建一个 formal session 再重绑
+- session 损坏或 schema 错误时不能偷偷重建，必须把错误暴露出来
+
+## 明确不是正式真相源的东西
+
+- prompt 文案
+- 可见事件输出
+- shell 展示缓存
+- JSONL 审计流
+- Telegram / 微信的展示消息
+- host runtime facade 自己的返回对象
+
+## 当前裁决顺序
+
+1. 先看控制面账本和 session 现场
+2. 再看由它们派生的 runtime / orchestration 语义
+3. 最后才看宿主展示和可见输出
+
+如果三者冲突，以前两者为准。
+
+## 当前升级边界
+
+1. control plane 通过 SQLite migration / `user_version` 升级。
+2. config 通过 `schemaVersion` 升级。
+3. session snapshot 通过 `schemaVersion` 升级。
+4. 升级失败必须在正式读取边界报错，不允许宿主或调用方静默兜底。

package/spec//347/224/250/346/210/267/345/256/241/351/230/205/README.md

@@ -0,0 +1,27 @@
+# 用户审阅
+
+这一层是给人类看的。
+
+它默认读者不是写代码的人，而是：
+
+- 决定项目方向的人
+- 审阅实现是否跑偏的人
+- 只看文档、不看实现细节的人
+
+## 你在这里应该看到什么
+
+你应该看到的是：
+
+- Athlete 的核心定位
+- 它服务什么样的用户
+- 它当前做什么、不做什么
+- 它为什么强调耐跑、总指挥、拆任务、派工和扩技能
+- 哪些原则是整个项目不能越线的
+
+你不应该在这里被迫理解：
+
+- 具体文件怎么 import
+- 哪个 store 的字段叫什么
+- 某个通道的细小接线细节
+
+这些内容都在 `技术实现/`。

package/spec//347/224/250/346/210/267/345/256/241/351/230/205//344/272/247/345/223/201/345/256/232/344/275/215.md

@@ -0,0 +1,78 @@
+# 产品定位
+
+## Athlete 现在是什么
+
+Athlete 不是一个“会在终端里聊天的 AI 员工”。
+
+它现在更准确的定位是：
+
+**一个以耐跑主 Agent 为核心、以任务拆分与调度为主轴、能够统领技能扩展与多通道执行的总指挥型智能体平台。**
+
+## 为什么要换这个定位
+
+如果把 Athlete 理解成一个“单枪匹马自己冲”的智能体，文档、架构和测试都会很容易跑偏。
+
+因为当前系统已经不只是：
+
+- 自己读文件
+- 自己跑命令
+- 自己写代码
+
+它还已经具备：
+
+- 主 Agent 预处理复杂任务
+- 持久化任务板
+- readiness / blocked / active / merge 的机器状态
+- lead / teammate / background / subagent 的路由
+- worktree 隔离并行执行
+- skills 和 MCP 的标准扩展口
+- CLI、Telegram、Weixin 等宿主接入
+
+所以它的核心角色已经不该再被描述成“一个普通超级员工”。
+
+它更像：
+
+- 一个能长期耐跑的主 Agent
+- 一个会组织别人干活的总指挥
+- 一个把工具、技能、通道和控制面统一起来的平台内核
+
+## 当前核心价值
+
+Athlete 当前最核心的价值不是“最像人聊天”，而是：
+
+- 长任务不容易跑丢
+- 出错后还能继续推进
+- 复杂任务能拆、能派、能等、能合流
+- 控制面知道任务为什么 ready、blocked、active、completed
+- 宿主只是外壳，主路径不会因为多通道接入而散掉
+- skills、MCP、工具和通道都能在统一边界下生长
+
+## 当前主要用户
+
+Athlete 当前服务的不是“偶尔问一句问题的人”，而是这些人：
+
+- 需要多步自动化的人
+- 需要反复整理文档、资料、表格、网页信息的人
+- 需要一个主 Agent 帮他统筹复杂工作的人
+- 需要把能力扩进现有 Agent 系统的人
+- 需要多宿主接入，但不想维护多套 runtime 规则的人
+
+## Athlete 不想成为什么
+
+Athlete 当前不想成为：
+
+- 纯聊天机器人
+- 只会自己埋头做事的单兵 Agent
+- 默认一堆 agent 乱跑的 swarm 表演器
+- 拖拽式工作流平台
+- 先堆满功能、再补真相源和边界的“看起来很全”的系统
+
+## 对实现的直接要求
+
+因为产品定位已经变了，所以实现和测试必须跟着变：
+
+- 文档必须优先表达“耐跑 + 总指挥 + 扩展平台”这条主线
+- 总体架构必须优先保护控制面和调度面
+- 新能力必须优先问“是否增强主 Agent 的组织能力”
+- 宿主层不能继续偷偷长平行真相
+- 技术文档必须直接服务文档驱动开发和测试驱动开发

package/spec/{principles/P06- → /347/224/250/346/210/267/345/256/241/351/230/205//345/256/252/346/263/225/345/216/237/345/210/231/06-}/344/270/212/344/270/213/346/226/207/350/246/201/350/203/275/345/216/213/347/274/251.md

@@ -18,6 +18,6 @@
 
 ## 当前对应
 
-- `src/agent/contextBuilder.ts`
-- `src/agent/managedTurn.ts`
+- `src/agent/context.ts`
+- `src/agent/turn/managed.ts`
 - `src/agent/retryPolicy.ts`

package/spec/{principles/P08- → /347/224/250/346/210/267/345/256/241/351/230/205//345/256/252/346/263/225/345/216/237/345/210/231/08-}/346/205/242/346/223/215/344/275/234/346/224/276/345/220/216/345/217/260.md

@@ -19,5 +19,5 @@ background 不是附属功能，它是 Athlete 耐跑能力的一部分。
 
 ## 当前对应
 
-- `src/background/`
+- `src/execution/`
 - `src/tools/background/`

package/spec/{principles/P13-session → /347/224/250/346/210/267/345/256/241/351/230/205//345/256/252/346/263/225/345/216/237/345/210/231/13-session}/346/230/257/344/273/273/345/212/241/347/216/260/345/234/272.md

@@ -25,6 +25,6 @@ session 里应该能承接：
 
 ## 当前对应
 
-- `src/agent/sessionStore.ts`
-- `src/agent/taskState.ts`
-- `src/agent/verificationState.ts`
+- `src/agent/session.ts`
+- `src/agent/session/taskState.ts`
+- `src/agent/verification.ts`

package/spec/{principles/P15-provider → /347/224/250/346/210/267/345/256/241/351/230/205//345/256/252/346/263/225/345/216/237/345/210/231/15-provider}/345/277/205/351/241/273/345/217/257/346/233/277/346/215/242.md

@@ -14,9 +14,11 @@ Athlete 要做 harness，不做某一家的皮肤。
 
 - 当前优先支持 OpenAI-compatible 接口
 - provider 选择属于配置层，不属于业务层
+- provider-specific fallback、reasoning、tool 兼容性都属于 adapter / capability 层，不属于 kernel 主循环
 
 ## 当前对应
 
+- `src/agent/provider.ts`
 - `src/agent/api.ts`
-- `src/config/env.ts`
+- `src/config/store.ts`
 - `src/types.ts`