@jun133/athlete 0.0.4 → 0.0.5

package/spec/modules/tool-registry.md

@@ -4,18 +4,23 @@
 
 Tool registry 负责向模型公开动作集合，并统一管理本地工具与 MCP 动态工具。
 
-## 当前组成
-
-- 本地内建工具
-- mode 过滤后的工具集
-- MCP 动态收集到的工具
+## 当前组成
+
+- 本地内建工具
+- mode 过滤后的工具集
+- MCP 动态收集到的工具
+- 统一治理后的 `entries / blocked` 结果
 
 ## 当前规则
 
 1. 新工具先注册，再暴露给模型。
 2. tool handler 只做动作，不做控制面真相发明。
-3. skill 不是工具替代品；skill 提供 workflow，tool 提供动作。
-4. MCP 工具也必须经过统一 registry，不走旁路。
+3. skill 不是工具替代品；skill 提供 workflow，tool 提供动作。
+4. MCP 工具也必须经过统一 registry，不走旁路。
+5. 工具暴露顺序、workflow fallback、change / verification signal 约束都由机器治理 metadata 决定，而不是靠 prompt 复述。
+6. metadata 缺失或不兼容时默认 fail-closed：
+   - 内建 / 本地 includeTools 直接报错
+   - MCP 工具进入 `blocked`，不暴露给模型
 
 ## 工具层职责
 
@@ -43,37 +48,90 @@ Tool registry 负责向模型公开动作集合，并统一管理本地工具与
 - `src/tools/shell/`
 - `src/tools/skills/`
 
-共享层仍在 `src/tools/` 根目录：
-
-- `registry.ts`
-- `runtimeRegistry.ts`
-- `shared.ts`
-- `types.ts`
-- `changeTracking.ts`
-
-## Playwright MCP 当前事实
-
-当前 Playwright 浏览器工具通过 runtime registry 暴露为：
-
-- `mcp_playwright_browser_navigate`
-- `mcp_playwright_browser_snapshot`
-- `mcp_playwright_browser_click`
+共享层仍在 `src/tools/` 根目录：
+
+- `registry.ts`
+- `runtimeRegistry.ts`
+- `governance.ts`
+- `routing.ts`
+- `shared.ts`
+- `types.ts`
+- `changeTracking.ts`
+
+## Playwright MCP 当前事实
+
+当前 Playwright adapter 通过 runtime registry 暴露一组 `mcp_playwright_browser_*` 工具；这是 adapter surface，不是上层 machine rule。
+
+当前 adapter 层常见名字包括：
+
+- `mcp_playwright_browser_navigate`
+- `mcp_playwright_browser_snapshot`
+- `mcp_playwright_browser_click`
 - `mcp_playwright_browser_type`
 - `mcp_playwright_browser_take_screenshot`
 - 以及其他 `mcp_playwright_browser_*`
-
-当前优先级策略：
-
-- runtime registry 会把 Playwright 浏览器工具排到本地文件工具和 shell 工具前面
-- request 级 tool priority 会在 web research / browser automation 场景继续把浏览器工具前置
-- `run_shell` 的网页抓取只应作为 fallback
+
+当前优先级策略：
+
+- runtime registry 先用治理 metadata 做 fail-closed 过滤，再按机器排序暴露工具
+- 浏览器工具会通过治理 metadata 稳定排到本地文件工具和 shell 工具前面
+- request 级 tool priority 会消费同一套 metadata，在 web research / browser automation 场景继续把浏览器 capability 工具前置
+- `run_shell` 与本地文件 detour 在 browser workflow 下只作为 fallback
+
+## 当前治理模型
+
+当前 registry 暴露给机器的不只是 tool schema，还包括：
+
+- `entries`: 每个已暴露工具的统一 governance metadata
+- `blocked`: 因 metadata 缺失、MCP 缺少可信只读提示、或治理不兼容而被 fail-closed 的工具
+
+当前 governance metadata 至少回答：
+
+- 是否只读 / 会不会修改状态
+- 是否高风险 / destructive
+- 是否要求 change signal / verification signal
+- 是否属于 browser capability
+- browser step 是 `navigate / snapshot / take_screenshot / click / type / other`
+- 是否属于 document-reading capability
+- document kind 是 `doc / image / pdf / ppt / spreadsheet`
+- 是否在特定 workflow 下只能 fallback
+- 是否并发安全
+
+## 当前上层约束
+
+上层 machine rule 当前必须遵守：
+
+1. workflow guard 只认 browser capability / browser step，不认具体 Playwright 工具名。
+2. tool priority 只认治理 metadata，不认具体 Playwright 工具名。
+3. document routing hint 只认 `document.read` / `spreadsheet.read` capability，不把 `mineru_*` 名字继续上推。
+4. acceptance / phase / verification 只认统一 signal，不认 adapter 工具名。
+
+## 当前代码落点
+
+- `src/tools/governance.ts`
+  - browser capability、browser step、document kind、fail-closed metadata
+- `src/tools/order.ts`
+  - 暴露排序
+- `src/agent/toolPriority.ts`
+  - request 级 tool priority，消费统一 metadata
+- `src/skills/workflowGuards.ts`
+  - 只输出 `suggestedCapability`
+- `src/tools/routing.ts`
+  - `document.read` / `spreadsheet.read` capability hint
+- `src/mcp/toolAdapter.ts`
+  - adapter 层把 MCP 工具接入 registry，保留 origin 信息
+
+## 对齐说明
+
+- adapter 层仍可以保留 `mcp_playwright_browser_*`、`mineru_*` 这类生态名词
+- 但 registry 暴露给上层的真相必须是 capability metadata，而不是生态字符串
 
 ## 当前约束
 
-如果某个动作：
-
-- 需要明确输入输出
-- 不适合塞进 prompt
-- 不该让模型自己拼 shell
-
-就应该做成工具，而不是继续加提示词。
+如果某个动作：
+
+- 需要明确输入输出
+- 不适合塞进 prompt
+- 不该让模型自己拼 shell
+
+就应该做成工具，而不是继续加提示词。

package/spec/modules//346/211/251/345/261/225/346/234/272/345/210/266.md

@@ -36,10 +36,10 @@ skills 已经是标准化 V1，而不是散装 prompt 片段。
 - `web-research`
 - `browser-automation`
 
-MinerU 文档 workflow 现在按类别拆成独立工具：
-
-- `mineru_pdf_read`
-- `mineru_image_read`
+MinerU 文档 workflow 现在按类别拆成独立工具：
+
+- `mineru_pdf_read`
+- `mineru_image_read`
 - `mineru_doc_read`
 - `mineru_ppt_read`
 
@@ -78,28 +78,64 @@ MinerU 文档 workflow 现在按类别拆成独立工具：
    - 提供使用策略
    - 当前是 `web-research` 与 `browser-automation`
 
-设计原则：
-
-- 联网能力先做成 `tool` 或 `MCP`
-- `skill` 只做 workflow
-- 不把底层联网继续堆进 `systemPrompt`
-
-## 当前接线点
-
-当前 skill / MCP / runtime 的接线点：
-
-- `src/context/projectContext.ts`
-- `src/tools/skills/loadSkillTool.ts`
-- `src/agent/systemPrompt.ts`
-- `src/agent/runTurn.ts`
-- `src/tools/runtimeRegistry.ts`
-- `src/mcp/registryIntegration.ts`
-
-## 当前约束
-
-当前扩展仍必须满足：
-
-- 不破坏 continuation / compact / recovery
-- 不让主循环继续长胖
-- 不新造平行技能体系
-- 不让 MCP 绕开统一 registry
+设计原则：
+
+- 联网能力先做成 `tool` 或 `MCP`
+- `skill` 只做 workflow
+- 不把底层联网继续堆进 `systemPrompt`
+
+## 当前 capability 边界
+
+当前扩展层已经明确区分：
+
+1. adapter / tool surface
+   - 可以保留 `@playwright/mcp`、`mineru_*` 这类生态名词
+2. runtime governance / workflow / acceptance
+   - 只认 capability / signal
+   - 不认具体生态字符串
+
+当前上层抽象：
+
+- browser capability
+  - `browser.navigate`
+  - `browser.snapshot`
+  - `browser.take_screenshot`
+  - `browser.click`
+  - `browser.type`
+- document capability
+  - `document.read`
+  - `spreadsheet.read`
+- acceptance signals
+  - `http_endpoint_verified`
+  - `web_page_verified`
+  - `document_read_completed`
+  - `structured_artifact_valid`
+
+## 当前接线点
+
+当前 skill / MCP / runtime 的接线点：
+
+- `src/context/projectContext.ts`
+- `src/tools/skills/loadSkillTool.ts`
+- `src/agent/systemPrompt.ts`
+- `src/skills/prompt.ts`
+- `src/agent/runTurn.ts`
+- `src/tools/governance.ts`
+- `src/tools/runtimeRegistry.ts`
+- `src/tools/routing.ts`
+- `src/mcp/registryIntegration.ts`
+- `src/mcp/toolAdapter.ts`
+- `src/agent/acceptance/signals.ts`
+
+## 当前约束
+
+当前扩展仍必须满足：
+
+- 不破坏 continuation / compact / recovery
+- 不让主循环继续长胖
+- 不新造平行技能体系
+- 不让 MCP 绕开统一 registry
+- skill prompt 只输出本轮决策相关的 runtime hint（loaded / selected / missing required），不回退成 catalog dump
+- MCP 工具进入 runtime registry 前必须先经过治理 metadata 归一化；安全信息不够时默认 fail-closed
+- browser-first / document routing / workflow fallback 由机器治理逻辑优先决定，prompt 只保留原则级说明
+- adapter 名词允许存在于工具实现、技能名、README、配置与测试中，但不允许继续进入上层 machine rule

package/spec/overview/v0/350/214/203/345/233/264.md

@@ -16,12 +16,13 @@
 - docx / spreadsheet 基础能力
 - background job
 
-### 控制面
-
-- 任务板持久化
-- teammate 名册与 inbox
-- 协议请求与审批状态
-- worktree 绑定与隔离
+### 控制面
+
+- 任务板持久化
+- machine-enforced orchestration lifecycle
+- teammate 名册与 inbox
+- 协议请求与审批状态
+- worktree 绑定与隔离
 
 ### 扩展
 

package/spec/overview//344/272/247/345/223/201/345/256/232/344/271/211.md

@@ -18,12 +18,13 @@ Athlete 是一个终端优先的 AI harness。
 
 **一个耐跑、可续跑、面向复杂任务的终端智能体框架。**
 
-它现在最强的价值不是“最会聊天”，而是：
-
-- 不容易中途断掉
-- 出错后会继续排查
-- 长任务能自动续跑
-- 多步任务有状态落盘
+它现在最强的价值不是“最会聊天”，而是：
+
+- 不容易中途断掉
+- 出错后会继续排查
+- 长任务能自动续跑
+- 多步任务有状态落盘
+- 任务派工和恢复不靠 prompt 记忆
 
 ## 下一阶段定位
 
@@ -31,12 +32,13 @@ Athlete 是一个终端优先的 AI harness。
 
 **一个以耐跑主 Agent 为核心、能够统筹任务与技能扩展的总指挥型智能体平台。**
 
-关键词：
-
-- 主 Agent 很强
-- 复杂任务时会拆分与调度
-- skills 是标准扩展口
-- 多 Agent 是按需能力，不是默认军团
+关键词：
+
+- 主 Agent 很强
+- 复杂任务时会拆分与调度
+- skills 是标准扩展口
+- 多 Agent 是按需能力，不是默认军团
+- 控制面知道任务为什么 ready / blocked / active / completed
 
 ## 目标用户
 

package/spec/principles/P06-/344/270/212/344/270/213/346/226/207/350/246/201/350/203/275/345/216/213/347/274/251.md

@@ -16,8 +16,8 @@
 
 这条原则直接保护 Athlete 当前最强的“耐跑能力”。
 
-## 当前对应
-
-- `src/agent/contextBuilder.ts`
-- `src/agent/managedTurn.ts`
-- `src/agent/retryPolicy.ts`
+## 当前对应
+
+- `src/agent/context.ts`
+- `src/agent/turn/managed.ts`
+- `src/agent/retryPolicy.ts`

package/spec/principles/P13-session/346/230/257/344/273/273/345/212/241/347/216/260/345/234/272.md

@@ -23,8 +23,8 @@ session 里应该能承接：
 - verification 状态
 - task state
 
-## 当前对应
-
-- `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/345/277/205/351/241/273/345/217/257/346/233/277/346/215/242.md

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

package/spec/principles/P18-/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

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

package/spec/principles/P20-/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/modules/lightweight-context-runtime.md`

package/spec/principles/P21-/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/architecture/运行时循环.md`

package/spec/principles/P22-/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/modules/session-resume-compact.md`

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