@jun133/athlete 0.0.2

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@jun133/athlete",
+  "version": "0.0.2",
+  "description": "A global terminal AI coding assistant.",
+  "keywords": [
+    "athlete",
+    "cli",
+    "ai",
+    "agent",
+    "coding"
+  ],
+  "bin": {
+    "athlete": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "spec",
+    "scripts/postinstall-playwright.mjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts --format cjs --platform node --target node20 --outDir dist --clean --sourcemap",
+    "check": "npm run typecheck && npm run build",
+    "dev": "tsx src/cli.ts",
+    "postinstall": "node scripts/postinstall-playwright.mjs",
+    "test:build": "node -e \"require('node:fs').rmSync('.test-build', { recursive: true, force: true })\" && tsc -p tsconfig.tests.json",
+    "test:core": "npm run test:build && node --test .test-build/tests/**/*.test.js",
+    "verify:skills-api": "npm run test:build && node scripts/verify-skills-v1.mjs",
+    "verify:runtime-context-api": "npm run test:build && node scripts/verify-runtime-lightweight-context-api.mjs",
+    "verify:runtime-checkpoint-api": "npm run test:build && node scripts/verify-runtime-checkpoint-api.mjs",
+    "verify:runtime-observability-api": "npm run test:build && node scripts/verify-runtime-observability-api.mjs",
+    "verify:mineru-documents-api": "npm run test:build && node scripts/verify-mineru-documents-api.mjs",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "test": "npm run check && npm run test:core"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.9.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@openilink/openilink-sdk-node": "^0.6.0",
+    "@playwright/mcp": "^0.0.70",
+    "@types/adm-zip": "^0.5.8",
+    "adm-zip": "^0.5.17",
+    "cfb": "^1.2.2",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.1",
+    "diff": "^8.0.2",
+    "docx": "^9.5.1",
+    "dompurify": "^3.3.3",
+    "dotenv": "^17.2.3",
+    "env-paths": "^3.0.0",
+    "execa": "^9.6.0",
+    "fast-glob": "^3.3.3",
+    "mammoth": "^1.10.0",
+    "marked": "^17.0.4",
+    "openai": "^6.4.0",
+    "silk-wasm": "^3.7.1",
+    "xlsx": "^0.18.5"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}

package/scripts/postinstall-playwright.mjs

@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
+
+const require = createRequire(import.meta.url);
+
+if (shouldSkipInstall()) {
+  process.exit(0);
+}
+
+const target = resolveInstallTarget(process.env.ATHLETE_MCP_PLAYWRIGHT_BROWSER);
+const cliPath = resolvePlaywrightCliPath();
+const location = readInstallLocation(cliPath, target);
+
+if (location === "<system>" || (location && fs.existsSync(location))) {
+  process.exit(0);
+}
+
+const result = spawnSync(process.execPath, [cliPath, "install", target], {
+  stdio: "inherit",
+  windowsHide: true,
+});
+
+if ((result.status ?? 1) !== 0) {
+  const message = `[athlete] Playwright browser bootstrap failed for "${target}". ` +
+    `You can retry later, or skip with ATHLETE_SKIP_PLAYWRIGHT_BROWSER_INSTALL=1.`;
+
+  if (isStrictInstall()) {
+    console.error(message);
+    process.exit(result.status ?? 1);
+  }
+
+  console.warn(message);
+}
+
+function resolveInstallTarget(rawValue) {
+  switch (String(rawValue ?? "").trim().toLowerCase()) {
+    case "chrome":
+      return "chrome";
+    case "firefox":
+      return "firefox";
+    case "webkit":
+      return "webkit";
+    case "msedge":
+      return "msedge";
+    default:
+      return "chrome";
+  }
+}
+
+function resolvePlaywrightCliPath() {
+  const packageJsonPath = require.resolve("playwright/package.json");
+  return path.join(path.dirname(packageJsonPath), "cli.js");
+}
+
+function readInstallLocation(cliPath, target) {
+  const result = spawnSync(process.execPath, [cliPath, "install", "--dry-run", target], {
+    encoding: "utf8",
+    windowsHide: true,
+  });
+
+  if ((result.status ?? 1) !== 0) {
+    return "";
+  }
+
+  const match = String(result.stdout ?? "").match(/Install location:\s+([^\r\n]+)/i);
+  return match?.[1]?.trim() ?? "";
+}
+
+function shouldSkipInstall() {
+  const value = String(process.env.ATHLETE_SKIP_PLAYWRIGHT_BROWSER_INSTALL ?? "").trim().toLowerCase();
+  return value === "1" || value === "true" || value === "yes";
+}
+
+function isStrictInstall() {
+  const value = String(process.env.ATHLETE_STRICT_PLAYWRIGHT_BROWSER_INSTALL ?? "").trim().toLowerCase();
+  return value === "1" || value === "true" || value === "yes";
+}

package/spec/README.md

@@ -0,0 +1,56 @@
+# Athlete SPEC
+
+`spec/` 是 Athlete 当前唯一的规范与维护文档源。
+
+这里描述的是：
+
+- 项目现在已经做到什么
+- 当前架构如何组织
+- 关键规则和边界是什么
+- 维护时应该改哪一层
+
+这里不负责：
+
+- 历史演进叙事
+- 营销式介绍
+- 运行产物归档
+
+## 单一真相源规则
+
+从现在开始：
+
+- 规范、原则、模块边界、维护说明统一写在 `spec/`
+- 根目录 `README.md` 只保留用户入口和高层说明
+- 根目录 `validation/` 只保留验证产物，不再承担规范文档职责
+
+## 阅读顺序
+
+1. `principles/README.md`
+2. `overview/产品定义.md`
+3. `overview/v0范围.md`
+4. `architecture/总体架构.md`
+5. `architecture/状态与真相源.md`
+6. `architecture/运行时循环.md`
+7. `modules/`
+8. `interfaces/`
+9. `implementation/`
+10. `testing/`
+11. `adr/`
+
+## 目录说明
+
+- `principles/`: 架构宪法与工程铁律
+- `overview/`: 产品定义、范围、边界
+- `architecture/`: 总体架构、真相源、主循环
+- `modules/`: 模块职责与约束
+- `interfaces/`: 核心接口契约
+- `repo/`: 仓库级规则与流程
+- `implementation/`: 当前目录与代码映射
+- `testing/`: 测试策略与 fail-first 列表
+- `adr/`: 关键架构决策记录
+
+## 文档要求
+
+1. 只写现状，不写过时历史说明。
+2. 如果文档与 `src/` 当前实现冲突，以当前实现为准，并及时改文档。
+3. 同类说明只保留一份，不并行维护 `docs/` 和 `spec/` 两套说法。

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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,19 @@
+# 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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,111 @@
+# 总体架构
+
+## 一句话
+
+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

@@ -0,0 +1,117 @@
+# 状态与真相源
+
+## 目标
+
+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

@@ -0,0 +1,82 @@
+# 运行时循环
+
+## 当前 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

@@ -0,0 +1,17 @@
+# 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

@@ -0,0 +1,55 @@
+# 模块级开发任务单
+
+## 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. 项目内经验沉淀