@vionwilliams/agent-os 1.0.0-alpha.5

package/LICENSE

@@ -0,0 +1,60 @@
+Agent-OS License
+================
+
+Copyright (c) 2026 VION WILLIAMS
+
+This repository contains two categories of source code with different
+licensing provenance. See the NOTICE section at the bottom of this file
+for the fork-heritage disclosure.
+
+--------------------------------------------------------------------------
+MIT License — applies to all original Agent-OS contributions
+--------------------------------------------------------------------------
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+--------------------------------------------------------------------------
+NOTICE — Upstream Fork Heritage
+--------------------------------------------------------------------------
+
+Agent-OS began as a fork of Anthropic's Claude Code CLI. Substantial
+portions of the execution-layer infrastructure (tool protocols, REPL
+surface, MCP integration, permission system, telemetry scaffolding, etc.)
+are derived from upstream Claude Code source.
+
+The Agent-OS additions — including but not limited to:
+
+  * Multi-Model Router and Cost Intelligence subsystem
+  * Knowledge Forge (FCA-based knowledge compilation engine)
+  * Super-Coordination layer (production lines, task board,
+    knowledge sync, Auto-OS evolution)
+  * BYOK hardening and the removal of subscription / OAuth paths
+
+are original works authored for Agent-OS and are licensed under the
+MIT terms above.
+
+Portions of this codebase derived from Anthropic's Claude Code remain
+subject to the license terms under which Anthropic distributes that
+software. Users intending to redistribute Agent-OS — particularly in
+commercial contexts — should review Anthropic's upstream license and
+consult legal counsel before doing so.
+
+"Claude", "Claude Code", and "Anthropic" are trademarks of Anthropic, PBC.
+Their use in this repository is limited to factual attribution of the
+fork heritage and does not imply endorsement.

package/README.md

@@ -0,0 +1,321 @@
+# Agent-OS
+
+> BYOK fork of Claude Code · Bring Your Own Provider · 自托管 AI 工程师工作站
+
+**Status**: `1.0.0-alpha.5` · Functional alpha · npm 发布链路已就绪（dry-run 通过）· 单人学习项目 fork
+
+---
+
+## 这是什么
+
+Agent-OS 是 Anthropic Claude Code 的一个 fork,目标是**移除 vendor lock-in**,让 Claude Code 这套已经成熟的 agent 编排能力可以接入任意 OpenAI-compatible provider,并彻底拆除托管端后台依赖(OAuth / 订阅 / 遥测回传)。
+
+**和原版 Claude Code 的核心差异**:
+
+| 维度 | Claude Code | Agent-OS |
+|---|---|---|
+| Auth | OAuth + Anthropic Pro/Team 订阅 | **BYOK only**(自带 key) |
+| Provider | Anthropic only | **多 provider 路由**(详见下) |
+| 遥测 | OpenTelemetry → BigQuery | **完全移除**(alpha.3 堵 BigQuery,alpha.4 下线 OTEL 管道) |
+| User-Agent | `claude-code/<v>` | `agent-os/<v>` |
+| 分发 | npm `@anthropic-ai/claude-code` | GitHub Releases 二进制 + from-source + npm alpha 通道（待首发） |
+| 托管特性 | Remote Control / Scheduled Agents / Teleport | 在 BYOK 模式下不可用 |
+
+---
+
+## 快速开始
+
+### 1. 二进制安装（推荐）
+
+> 适合最终用户: 不需要 Bun,下载即可运行。
+
+```bash
+# 安装最新版（macOS/Linux）
+curl -fsSL https://raw.githubusercontent.com/VIONWILLIAMS/agent-os/main/scripts/install.sh | bash
+
+# 或指定版本
+curl -fsSL https://raw.githubusercontent.com/VIONWILLIAMS/agent-os/main/scripts/install.sh | \
+  bash -s -- --version v1.0.0-alpha.5
+
+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`
+
+### 2. 从源码安装（开发者）
+
+```bash
+git clone https://github.com/VIONWILLIAMS/agent-os.git
+cd agent-os
+bun install
+bash scripts/build.sh
+```
+
+前置:[Bun](https://bun.sh) `>= 1.3.0`。构建产物是单文件 `dist/cli.js`(约 18 MB · 自带 shebang · 可直接执行)。
+
+### 3. 配置 BYOK provider
+
+选任意一条路径填 `.env` 或 export 到 shell 环境(`.env.example` 给了模板):
+
+```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_NAME="deepseek-chat"
+
+# Path D · Qwen / 通义千问(router 模式)
+export MODEL_PROVIDER="qwen"
+export MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
+export QWEN_API_KEY="sk-..."
+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"
+
+# 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"
+
+# Path G · Ollama 本地(router 模式 · 自动识别 localhost:11434)
+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 模式
+
+# 或通过 bun（源码模式）
+bun dist/cli.js --version
+
+# 或全局链接（源码模式可选）
+bun link                        # 注册到 PATH
+agent-os --version              # 全局可用
+bun unlink                      # 清理
+```
+
+---
+
+## 支持的 Provider
+
+下表是 `src/services/api/router/keyDetector.ts` 中 `KNOWN_PROVIDERS` 的实际清单。Router 层支持这些 provider 的自动识别、base URL 预设和默认模型选择:
+
+| 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` 自动识别 |
+
+> **不在表内** 的任何 OpenAI Chat Completions 兼容 endpoint 也可以接入:用 `MODEL_PROVIDER` + `MODEL_BASE_URL` + provider 专属 `<NAME>_API_KEY` 或通用 `MODEL_API_KEY` 三个 env var 注入即可。
+
+Router 的三种 provider 实现分别在 `src/services/api/router/providers/`:
+- `anthropic.ts` — Anthropic SDK 原生流式
+- `openai-compat.ts` — OpenAI Chat Completions 协议(绝大多数 provider)
+- (Ollama 复用 `openai-compat` · 由 base URL 自动降级)
+
+---
+
+## BYOK 配置层级
+
+Router 配置按四层优先级解析,先命中者生效。来源:`src/services/api/router/config.ts:loadRouterConfig()`。
+
+### Layer 1 · `MODEL_ROUTER` 环境变量快捷格式
+
+最小例子 · 单行指定 provider/key/endpoint:
+
+```bash
+export MODEL_ROUTER="minimax:sk-cp-xxx@https://api.minimax.chat/v1"
+```
+
+格式:`<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"
+  }
+}
+```
+
+### Layer 4 · 用户级 `~/.claude/model-router.json`
+
+同样的 JSON 格式,放在 `$HOME/.claude/model-router.json`。
+
+> ⚠️ **BYOK 守护**:当 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_BASE_URL` 已设置时,这层**完全不被读取**。这是为了避免一台机器上遗留的 router 配置静默压过 `.env` 里显式配的 Anthropic 凭据。Layer 1-3 是显式 opt-in,不受此守护影响。
+
+未命中任何一层时,router 返回 `null`,走原生 Anthropic SDK 路径(即 `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` 直连)。
+
+---
+
+## 启动校验
+
+Agent-OS 启动时会调用 `assertProviderConfigured()`(`src/utils/assertProvider.ts`),以下条件**任意一条成立**即放行:
+
+| 放行条件 | 含义 |
+|---|---|
+| `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)`。
+
+> 注意:用户级 `~/.claude/model-router.json` **单独存在** 不算 opt-in。启动校验不把它计入放行条件,避免一台机器上的旧 router 配置在你以为走 BYOK 时静默接管。
+
+---
+
+## 从 Claude Code 继承的能力
+
+Agent-OS 继承了 Claude Code 已经成熟的 agent 编排能力:
+
+- **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
+
+具体工具清单以 `./dist/cli.js --help` 为准。
+
+---
+
+## Roadmap
+
+- [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)。
+
+---
+
+## 已知限制
+
+- **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 审批。
+
+---
+
+## 卸载 / 回到 Claude Code
+
+Agent-OS 不接管系统 PATH,不写系统目录,不注册开机启动项。所有产物都在项目目录内。
+
+```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
+```
+
+`~/.claude/` 下的 settings / plugins / session 历史是 Claude Code 上游格式,Agent-OS 共用同一路径(alpha.5 之前);删除项目目录不会影响原版 Claude Code 的 `~/.claude/` 数据。
+
+---
+
+## License & 致谢
+
+MIT License · 详见 [LICENSE](./LICENSE)。Agent-OS 始于对 Anthropic Claude Code 的 fork,原始 Claude Code 部分仍受上游许可条款约束。
+
+This is a personal learning fork. 商业化使用待完整 vendor decoupling + license 终审完成后另行决定。
+
+"Claude"、"Claude Code"、"Anthropic" 是 Anthropic, PBC 的商标,本仓库中的使用仅为客观声明 fork 渊源。
+
+---
+
+## 链接
+
+- Repository: <https://github.com/VIONWILLIAMS/agent-os>
+- Releases: <https://github.com/VIONWILLIAMS/agent-os/releases>
+- Issues: <https://github.com/VIONWILLIAMS/agent-os/issues>
+- Changelog: [CHANGELOG.md](./CHANGELOG.md)