npm - @vionwilliams/agent-os - Versions diffs - 1.0.0-alpha.7 → 1.0.0-alpha.9 - Mend

@vionwilliams/agent-os 1.0.0-alpha.7 → 1.0.0-alpha.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -2,15 +2,25 @@
 > 智能任务通用工作系统 · 多模型路由 + 意图编排 + 多智能体协调 + DataHub + 可编程面板 + LLM 知识编译器
-**Status**: `1.0.0-alpha.7` · Beta 测试版 · npm 公共包已上线
+**Status**: `1.0.0-alpha.9` · Beta 测试版 · npm 公共包可用
 ---
 ## 这是什么
-Agent-OS 是一套面向真实工作的 AI 操作系统。它把**多模型路由、意图编排、多智能体协调、DataHub 数据枢纽、可编程面板系统、LLM 知识编译器**合成到同一个工作界面里，让 AI 从一次性调用走向持续运转的工作系统。
+Agent-OS 是一套面向真实工作的 AI 操作系统。它把**多模型路由、意图编排、多智能体协调、DataHub 数据枢纽、可编程面板系统、LLM 知识编译器**合成到同一个工作界面里，让 AI 从一次性调用走向持续运转的任务系统。
-**核心能力结构**:
+它的目标不是“多一个会对话的窗口”，而是把任务从输入到执行到沉淀完整跑通：
+- 一句任务进入系统
+- 系统持续理解与分流
+- 调度执行与状态回写
+- 结果可视化呈现
+- 经验沉淀为可复用知识
+---
+## 核心能力
 | 模块 | 说明 |
 |---|---|
@@ -25,296 +35,226 @@ Agent-OS 是一套面向真实工作的 AI 操作系统。它把**多模型路
 ## 快速开始
-### 1. 二进制安装（推荐）
+### 0. 前置环境
+```bash
+node -v
+bun -v
+```
+要求：
+- Node.js `>= 20`
+- Bun `>= 1.3.0`
-> 适合最终用户: 不需要 Bun,下载即可运行。
+### 1. npm 安装（推荐）
 ```bash
-# 安装最新版（macOS/Linux）
-curl -fsSL https://raw.githubusercontent.com/VIONWILLIAMS/agent-os/main/scripts/install.sh | bash
+npm install -g @vionwilliams/agent-os
+agent-os --version
+```
-# 或指定版本
-curl -fsSL https://raw.githubusercontent.com/VIONWILLIAMS/agent-os/main/scripts/install.sh | \
-  bash -s -- --version v1.0.0-alpha.5
+### 2. 二进制安装
+```bash
+curl -fsSL https://raw.githubusercontent.com/VIONWILLIAMS/agent-os/main/scripts/install.sh | bash
 agent-os --version
 ```
-手动下载也可用:[Releases](https://github.com/VIONWILLIAMS/agent-os/releases) 里按平台选择:
-- `agent-os-darwin-arm64`
-- `agent-os-darwin-x64`
-- `agent-os-linux-x64`
-- `agent-os-windows-x64.exe`
+> 注意：二进制安装依赖 GitHub Releases 的 latest 标签；若 release 未同步到最新版本，优先使用 npm 安装。
-### 2. 从源码安装（开发者）
+### 3. 从源码运行（开发者）
 ```bash
 git clone https://github.com/VIONWILLIAMS/agent-os.git
 cd agent-os
 bun install
 bash scripts/build.sh
+bun dist/cli.js --version
 ```
-前置:[Bun](https://bun.sh) `>= 1.3.0`。构建产物是单文件 `dist/cli.js`(约 18 MB · 自带 shebang · 可直接执行)。
+---
-### 3. 配置 BYOK provider
+## Provider 配置示例
-选任意一条路径填 `.env` 或 export 到 shell 环境(`.env.example` 给了模板):
+你可以使用统一 Router 变量：
 ```bash
-# Path A · 自定义 endpoint(推荐 · BYOK 本义)
-# 任何 OpenAI Chat Completions 兼容的 endpoint 都能接入
-export ANTHROPIC_BASE_URL="https://your-gateway.example.com/v1"
-export ANTHROPIC_API_KEY="your-key"
-# Path B · Anthropic 官方
-export ANTHROPIC_API_KEY="sk-ant-..."
-# Path C · DeepSeek(router 模式)
 export MODEL_PROVIDER="deepseek"
 export MODEL_BASE_URL="https://api.deepseek.com/v1"
-export DEEPSEEK_API_KEY="sk-..."
+export MODEL_API_KEY="your-key"
 export MODEL_NAME="deepseek-chat"
+```
-# Path D · Qwen / 通义千问(router 模式)
+也可以使用 provider 专属 key：
+```bash
 export MODEL_PROVIDER="qwen"
 export MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
-export QWEN_API_KEY="sk-..."
+export QWEN_API_KEY="your-key"
 export MODEL_NAME="qwen-plus"
+```
-# Path E · Moonshot / 月之暗面(router 模式)
-export MODEL_PROVIDER="moonshot"
-export MODEL_BASE_URL="https://api.moonshot.cn/v1"
-export MOONSHOT_API_KEY="sk-..."
-export MODEL_NAME="moonshot-v1-32k"
+Anthropic 直连同样支持：
-# Path F · GLM / 智谱(router 模式)
-export MODEL_PROVIDER="glm"
-export MODEL_BASE_URL="https://open.bigmodel.cn/api/paas/v4"
-export GLM_API_KEY="your-key"
-export MODEL_NAME="glm-4-flash"
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
-# Path G · Ollama 本地(router 模式 · 自动识别 localhost:11434)
+本地 Ollama 示例：
+```bash
 export MODEL_PROVIDER="ollama"
 export MODEL_BASE_URL="http://localhost:11434/v1"
 export MODEL_NAME="qwen2.5-coder:32b"
-# Path H · AWS Bedrock(BYO AWS)
-export CLAUDE_CODE_USE_BEDROCK=1
-export AWS_ACCESS_KEY_ID="..."
-export AWS_SECRET_ACCESS_KEY="..."
-export AWS_REGION="us-west-2"
-# Path I · Google Vertex AI(BYO GCP)
-export CLAUDE_CODE_USE_VERTEX=1
-export GOOGLE_APPLICATION_CREDENTIALS="/path/to/sa.json"
-export CLOUD_ML_REGION="us-east5"
 ```
-### 4. 运行
+---
+## 启动与运行
 ```bash
-# 直接执行(有 shebang)
-./dist/cli.js --version         # → 1.0.0-alpha.5 (Agent-OS)
-./dist/cli.js                   # 交互模式(REPL)
-./dist/cli.js -p "hi"           # 一次性 print 模式
+# 交互模式
+agent-os
-# 或通过 bun（源码模式）
-bun dist/cli.js --version
+# 一次性模式
+agent-os -p "帮我拆解今天的产品任务"
-# 或全局链接（源码模式可选）
-bun link                        # 注册到 PATH
-agent-os --version              # 全局可用
-bun unlink                      # 清理
+# 查看帮助
+agent-os --help
 ```
 ---
-## 支持的 Provider
+## 新用户首跑验收（建议 3 分钟完成）
-下表是 `src/services/api/router/keyDetector.ts` 中 `KNOWN_PROVIDERS` 的实际清单。Router 层支持这些 provider 的自动识别、base URL 预设和默认模型选择:
+```bash
+# 1) 版本确认
+agent-os --version
-| Provider | 类型 | Base URL | 默认 model | 备注 |
-|---|---|---|---|---|
-| **Anthropic** | `anthropic` | `https://api.anthropic.com` | `claude-sonnet-4-6` | 官方直连 · 最佳 tool use 质量 · 识别 `sk-ant-` 前缀 |
-| **DeepSeek** | `openai-compatible` | `https://api.deepseek.com/v1` | `deepseek-chat` | 识别 32-hex `sk-` 前缀 · 低成本 |
-| **Qwen / 通义千问** | `openai-compatible` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-plus` | 阿里 DashScope 兼容模式 |
-| **Moonshot / 月之暗面** | `openai-compatible` | `https://api.moonshot.cn/v1` | `moonshot-v1-8k` | 128k context 家族 |
-| **GLM / 智谱** | `openai-compatible` | `https://open.bigmodel.cn/api/paas/v4` | `glm-4-flash` | 识别 `glm-` 前缀 |
-| **MiniMax** | `openai-compatible` | `https://api.minimax.chat/v1` | `MiniMax-M2.7-HighSpeed` | 识别 `sk-cp-` 前缀 |
-| **Ollama** | `ollama` | `http://localhost:11434/v1` | (由 `MODEL_NAME` 指定) | 本地模型 · base URL 含 `localhost:11434` 自动识别 |
+# 2) 配置一组 provider（示例：DeepSeek）
+export MODEL_PROVIDER="deepseek"
+export MODEL_BASE_URL="https://api.deepseek.com/v1"
+export MODEL_API_KEY="your-key"
+export MODEL_NAME="deepseek-chat"
-> **不在表内** 的任何 OpenAI Chat Completions 兼容 endpoint 也可以接入:用 `MODEL_PROVIDER` + `MODEL_BASE_URL` + provider 专属 `<NAME>_API_KEY` 或通用 `MODEL_API_KEY` 三个 env var 注入即可。
+# 3) 打开路由调试并做最小请求
+MODEL_DEBUG=1 agent-os -p "Reply with exactly: pong" < /dev/null
+```
-Router 的三种 provider 实现分别在 `src/services/api/router/providers/`:
-- `anthropic.ts` — Anthropic SDK 原生流式
-- `openai-compat.ts` — OpenAI Chat Completions 协议(绝大多数 provider)
-- (Ollama 复用 `openai-compat` · 由 base URL 自动降级)
+若返回 `pong` 且日志里看到 `resolved config`，说明安装与路由链路正常。
 ---
-## BYOK 配置层级
+## Router 配置优先级
-Router 配置按四层优先级解析,先命中者生效。来源:`src/services/api/router/config.ts:loadRouterConfig()`。
+Router 配置按优先级从高到低解析：
-### Layer 1 · `MODEL_ROUTER` 环境变量快捷格式
-最小例子 · 单行指定 provider/key/endpoint:
-```bash
-export MODEL_ROUTER="minimax:sk-cp-xxx@https://api.minimax.chat/v1"
-```
+1. `MODEL_ROUTER`（快捷格式）
+2. `MODEL_PROVIDER` / `MODEL_BASE_URL` / `MODEL_API_KEY` / `MODEL_NAME`
+3. 项目级 `./model-router.json`
+4. 用户级 router 配置文件
-格式:`<provider>:<apiKey>@<baseUrl>`。解析器是 `parseEnvShorthand()`。
+说明：
-### Layer 2 · 单独 env vars
-按 `loadFromEnvVars()` 构造 provider:
-```bash
-export MODEL_PROVIDER="deepseek"
-export MODEL_BASE_URL="https://api.deepseek.com/v1"
-export DEEPSEEK_API_KEY="sk-..."       # 或通用 MODEL_API_KEY
-export MODEL_NAME="deepseek-chat"       # 可选
-```
-同时设置 `ANTHROPIC_API_KEY` 或 base URL 包含 `anthropic.com` 时,自动切换到 `type: 'anthropic'`;base URL 含 `localhost:11434` 时自动切到 `type: 'ollama'`。
-### Layer 3 · 项目级 `./model-router.json`
-最小例子,放在 cwd 下:
-```json
-{
-  "default": "deepseek/deepseek-chat",
-  "providers": {
-    "deepseek": {
-      "type": "openai-compatible",
-      "baseUrl": "https://api.deepseek.com/v1",
-      "apiKey": "sk-...",
-      "models": ["deepseek-chat", "deepseek-coder"]
-    },
-    "anthropic": {
-      "type": "anthropic",
-      "baseUrl": "https://api.anthropic.com",
-      "apiKey": "sk-ant-..."
-    }
-  },
-  "routes": [
-    { "when": "high_complexity", "use": "anthropic/claude-sonnet-4-6" },
-    { "when": "default",         "use": "deepseek/deepseek-chat" }
-  ],
-  "fallback": {
-    "deepseek": "anthropic/claude-sonnet-4-6"
-  }
-}
-```
+- 命中更高优先级后，低优先级不生效。
+- 推荐在项目里使用 `model-router.json` 固化团队默认路由。
+- 用户级默认目录为 `~/.agent-os/`（兼容变量可覆盖，详见 `docs/ROUTER.md`）。
-### Layer 4 · 用户级 `~/.claude/model-router.json`
+---
-同样的 JSON 格式,放在 `$HOME/.claude/model-router.json`。
+## 当前已支持的主流 Provider
-> ⚠️ **BYOK 守护**:当 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_BASE_URL` 已设置时,这层**完全不被读取**。这是为了避免一台机器上遗留的 router 配置静默压过 `.env` 里显式配的 Anthropic 凭据。Layer 1-3 是显式 opt-in,不受此守护影响。
+| Provider | 类型 | Base URL | 默认 model |
+|---|---|---|---|
+| Anthropic | `anthropic` | `https://api.anthropic.com` | `claude-sonnet-4-6` |
+| DeepSeek | `openai-compatible` | `https://api.deepseek.com/v1` | `deepseek-chat` |
+| Qwen | `openai-compatible` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-plus` |
+| Moonshot | `openai-compatible` | `https://api.moonshot.cn/v1` | `moonshot-v1-8k` |
+| GLM | `openai-compatible` | `https://open.bigmodel.cn/api/paas/v4` | `glm-4-flash` |
+| MiniMax | `openai-compatible` | `https://api.minimax.chat/v1` | `MiniMax-M2.7-HighSpeed` |
+| Ollama | `ollama` | `http://localhost:11434/v1` | 由 `MODEL_NAME` 指定 |
-未命中任何一层时,router 返回 `null`,走原生 Anthropic SDK 路径(即 `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` 直连)。
+任何 OpenAI Chat Completions 兼容 endpoint 都可以接入。
 ---
-## 启动校验
+## 常见问题（安装与首跑）
-Agent-OS 启动时会调用 `assertProviderConfigured()`(`src/utils/assertProvider.ts`),以下条件**任意一条成立**即放行:
+### 1) `agent-os --version` 显示旧版本
-| 放行条件 | 含义 |
-|---|---|
-| `ANTHROPIC_API_KEY` 非空 | BYOK 基础路径 |
-| `ANTHROPIC_BASE_URL` 非空 | 自定义 endpoint(含自建网关) |
-| `CLAUDE_CODE_USE_BEDROCK=1` | AWS Bedrock(BYO AWS 凭据) |
-| `CLAUDE_CODE_USE_VERTEX=1` | Google Vertex AI(BYO GCP 凭据) |
-| `MODEL_ROUTER` 非空 | Router 快捷格式 |
-| `MODEL_PROVIDER` 非空 | Router 单 env 格式 |
-| `MODEL_BASE_URL` 非空 | Router 通用 endpoint |
-| `./model-router.json` 存在 | 项目级 router 配置 |
+先确认命令来源：
-全都没有 → stderr 打印清晰指引(指向 `.env.example` 和本 README) → `exit(1)`。
+```bash
+which agent-os
+type agent-os
+```
-> 注意:用户级 `~/.claude/model-router.json` **单独存在** 不算 opt-in。启动校验不把它计入放行条件,避免一台机器上的旧 router 配置在你以为走 BYOK 时静默接管。
+如果你本地有自定义 alias/function，会覆盖 npm 全局安装。
----
+### 2) `[provider] API error 401 invalid api key`
-## 从 Claude Code 继承的能力
+优先排查环境变量污染：
-Agent-OS 继承了 Claude Code 已经成熟的 agent 编排能力:
+```bash
+unset MODEL_API_KEY MINIMAX_API_KEY DEEPSEEK_API_KEY
+```
-- **Agent Loop**:tool use · sub-agent 调度 · planning · compact
-- **File Tools**:Read / Edit / Write / Glob / Grep / NotebookEdit
-- **Shell Tools**:Bash(含权限沙箱)· Background 任务 · stream-json 输出
-- **Web Tools**:WebFetch · WebSearch
-- **Planning**:ExitPlanMode 等 task 工具 · TaskCreate/Update 追踪
-- **MCP**:完整的 Model Context Protocol client · stdio/http/sse transport
-- **Plugin / Skill**:插件加载 · skill 自动发现 · slash command
-- **权限管控**:allow/deny rules · 命令 allowlist · 权限 prompt
+然后只保留一组 provider 配置重试，并开启 `MODEL_DEBUG=1` 观察实际命中 provider/baseUrl/model。
-具体工具清单以 `./dist/cli.js --help` 为准。
+### 3) 不确定配置文件放在哪里
----
+默认看：
-## Roadmap
+- `~/.agent-os/model-router.json`
+- `~/.agent-os/providers.json`
-- [x] `alpha.1` — BYOK first public alpha · 品牌重写 · 发布元信息
-- [x] `alpha.2` — BYOK 守护硬化(endpoint 优先 + 启动校验 + 静默兜底删除)
-- [x] `alpha.3` — Phase 2.1 hotfix(身份合成修正 + BigQuery 遥测堵塞)
-- [x] `alpha.4` — Telemetry purge(OTEL 下线 · −400 KB bundle · 启动 −150~300 ms)+ User-Agent rebrand + build 脚本修复
-- [ ] `alpha.5` — 配置路径解耦(`~/.claude/` → `~/.agent-os/`)
-- [ ] `alpha.6+` — 内部 prompts / help 残留品牌清洗 · 151 处 `ClaudeCode*` 标识符重命名
-- [ ] `beta.1` — Knowledge Forge + 超协体集成完整化
-- [ ] `beta.2` — License 终审 + npm publish 决策
-完整变更记录见 [CHANGELOG.md](./CHANGELOG.md)。
+更多细节见：[`docs/ROUTER.md`](./docs/ROUTER.md)。
 ---
-## 已知限制
+## 主要目录
-- **Tool use 能力差异**:agent loop 的工具编排是按 Claude Sonnet / Opus 设计的;DeepSeek / Qwen / GLM 等做基础对话和简单 tool 没问题,复杂 sub-agent 编排与 planning 可能降级。生产使用建议 Anthropic 直连或 `high_complexity` 路由到 Claude 家族。
-- **品牌残留**:内部 prompts / help text 仍有部分 "Claude Code" 字串(UX 层,不影响功能);151 处内部 `ClaudeCode*` PascalCase/camelCase 标识符延后到 alpha.6+ 一次性重命名。
-- **配置路径**:仍依赖 `~/.claude/`(settings / router / plugins)· `alpha.5` 迁移到 `~/.agent-os/`。
-- **TypeScript baseline**:≥100 个 pre-existing errors(legacy 债,不影响 `bun build` 产物;`tsc --noEmit` 尚未 clean)。
-- **Anthropic 托管特性在 BYOK 模式不可用**:Remote Control(`/remote-control`)、Scheduled Remote Agents(`/schedule`)、Teleport、Passes、Extra-Usage 等依赖 `claude.ai/code` 后台的命令在本分发版中无法工作 —— 相关模块已 stub 或删除。
-- **npm 未正式首发**:已完成 `npm publish --dry-run --tag alpha` 验证；执行正式发布前需要 npm 账号登录（`npm whoami` 可用）并完成 release 审批。
+```text
+src/
+  coordination/         # 协调层 + 灵枢 + DataHub + 面板引擎
+  services/api/router/  # 多模型路由
+  panel-ui/             # 面板前端
+packages/
+  knowledge-forge/      # LLM 知识编译器
+```
 ---
-## 卸载 / 回到 Claude Code
+## 已知限制（Beta 阶段）
-Agent-OS 不接管系统 PATH,不写系统目录,不注册开机启动项。所有产物都在项目目录内。
+- 部分高复杂度任务在不同模型之间表现差异明显，建议根据任务类型设置路由策略。
+- TypeScript 仍有历史类型债，`bun build` 可用但 `tsc --noEmit` 尚未完全清零。
+- 个别历史命名的环境变量仍保持兼容（后续版本会逐步统一）。
-```bash
-# 二进制安装用户
-curl -fsSL https://raw.githubusercontent.com/VIONWILLIAMS/agent-os/main/scripts/uninstall.sh | bash
+---
-# 源码安装用户: 清理 bun link(如果链接过)
-cd ~/Projects/agent-os && bun unlink
+## 版本路线
-# 删除项目即卸载
-rm -rf ~/Projects/agent-os
-```
+- `alpha.7`：产品定位与 npm 介绍升级
+- `alpha.8`：README 全量去品牌化清稿
+- `alpha.9`：新用户首跑闭环补齐（版本一致性 / Router 文档 / 401 排障）
+- `beta.1`：知识编译器与协调层深度联动稳定化
+- `beta.2`：发布链路与文档体系标准化
-`~/.claude/` 下的 settings / plugins / session 历史是 Claude Code 上游格式,Agent-OS 共用同一路径(alpha.5 之前);删除项目目录不会影响原版 Claude Code 的 `~/.claude/` 数据。
+完整变更记录见 [CHANGELOG.md](./CHANGELOG.md)。
 ---
-## License & 致谢
-MIT License · 详见 [LICENSE](./LICENSE)。Agent-OS 始于对 Anthropic Claude Code 的 fork,原始 Claude Code 部分仍受上游许可条款约束。
-This is a personal learning fork. 商业化使用待完整 vendor decoupling + license 终审完成后另行决定。
+## License
-"Claude"、"Claude Code"、"Anthropic" 是 Anthropic, PBC 的商标,本仓库中的使用仅为客观声明 fork 渊源。
+MIT License · 详见 [LICENSE](./LICENSE)
 ---
 ## 链接
+- npm: <https://www.npmjs.com/package/@vionwilliams/agent-os>
 - Repository: <https://github.com/VIONWILLIAMS/agent-os>
 - Releases: <https://github.com/VIONWILLIAMS/agent-os/releases>
 - Issues: <https://github.com/VIONWILLIAMS/agent-os/issues>