@offerpilot/axiomruntime 0.0.1

package/README.md

@@ -0,0 +1,185 @@
+# AI Runtime（当前阶段：AI Gateway）
+
+本项目的长期目标是构建一套企业级 AI Runtime：让模型、Agent、记忆、知识、技能、工作流和工具在统一的运行、治理与学习体系中协作，并持续把个人经验沉淀为组织能力。
+
+Runtime 才是产品。Memory、Agent 和 LLM 都是可以替换和组合的能力模块。
+
+当前可用版本是 Runtime 的 Gateway 基础层：通过统一的 `ai` 命令管理 Claude Code 和 Codex CLI 的 provider、模型、优先级、健康度、故障转移、用量、会话、诊断与 Telegram 入口。后续能力会在保持现有命令稳定的基础上，逐步演进到统一执行、受治理学习、Skill/Capability 沉淀和组织级共享。
+
+北极星目标：**每一次交互，都让 Runtime 更有能力。**
+
+## 文档导航
+
+- [中文文档总览](./docs/README.md)
+- [doc_2.0 文档层总览](./docs/README.md)
+- [中文使用指南](./docs/usage.md)
+- [HTML 命令手册](./docs/USAGE.html)
+- [整体架构与当前实现快照](./docs/00-overview.md)
+
+AI 与维护者使用的英文权威文档位于 `AGENTS.md`、`docs/AI_RUNTIME_ARCHITECTURE.md` 和 `docs/CONVENTIONS.md`；产品规范、宪法摘要、记忆/学习与 Telegram 设计等构成 `doc_2.0` 文档层（现已展开在 `docs/` 与 `docs/modules/` 下，索引见 `docs/README.md`）。
+
+## 当前边界
+
+- 已交付：本地 Provider Gateway、Claude/Codex 启动与 fallback、Telegram、会话、用量、诊断和早期 Memory。
+- 演进中：统一 Runtime 执行上下文、自动学习与记忆治理、Skill/Capability 生命周期、插件体系。
+- 长期方向：组织与租户隔离、能力注册与共享、企业集成、Web/Desktop/API 治理界面。
+
+## 通过 npm 安装
+
+运行环境需要 Node.js `22.19.0` 或更高版本。全局安装后，npm 会把本包注册为 `ai` 命令：
+
+```bash
+npm install --global @offerpilot/axiomruntime
+ai --version
+ai setup
+```
+
+`ai --version` 用于验证 npm 包和命令安装成功；`ai setup` 初始化 Runtime 配置，并可在确认后安装缺失的 Claude Code/Codex。之后可直接运行 `ai`。
+
+## 通过 Homebrew 安装
+
+发布流程会在 npm 发布成功后把 `Formula/axiomruntime.rb` 同步到 `offerpilot/homebrew-tap`。Tap 建立后可使用：
+
+```bash
+brew tap offerpilot/tap
+brew install axiomruntime
+ai --version
+ai setup
+```
+
+如果 Tap 不托管在 GitHub，需要在首次添加时显式提供公开 Git 地址：
+
+```bash
+brew tap offerpilot/tap <homebrew-tap-public-git-url>
+```
+
+## 安装开发依赖
+
+运行和开发需要 Node.js `22.19.0` 或更高版本。该下限与锁定依赖的运行时要求一致；Node.js 20 不受支持。
+
+```bash
+npm install
+```
+
+## 本机 CLI 前置条件
+
+AI Gateway 不内置 Claude Code 或 Codex。它们作为彼此独立的外部 CLI 使用，需要先在本机安装并能通过 `PATH` 或常见安装路径找到。
+
+可用下面的命令初始化和检查：
+
+```bash
+ai setup
+ai doctor
+```
+
+## 构建
+
+```bash
+npm run build
+```
+
+## 本地测试
+
+```bash
+npm test
+```
+
+## 内网 Runtime 服务
+
+常驻服务为其他应用提供两类受鉴权接口，同时保留现有 `ai` CLI 和 Telegram 行为：
+
+- `POST /v1/chat/completions`、`/v1/responses`、`/v1/embeddings`：OpenAI 兼容模型调用，按 provider 优先级、模型目录、健康度和熔断状态自动切换。
+- `POST /v1/agent/runs`：复用 Telegram 背后的 Claude/Codex Engine。只接受受控 `workspace_id`，默认 `read_only`，服务端限制并发和超时。
+- `GET /health/live`、`/health/ready`：不含 Secret 的存活与就绪检查；其他接口必须使用 Bearer Token。
+
+```bash
+npm run build
+AI_GATEWAY_SERVER_TOKEN='replace-me' npm run server
+```
+
+生产 Compose 位于 `deploy/docker-compose.prod.yml`，默认仅映射宿主机 `127.0.0.1:8020`，并加入外部 Docker 网络 `ai-runtime`。Provider 配置挂载到 `/var/lib/ai-gateway`，服务 Token 通过只读文件挂载，不写入镜像或仓库。
+
+### GitLab 自动部署
+
+默认分支提交通过测试后，GitLab CI 会构建以 commit SHA 标记的镜像，并由锁定当前项目的受保护 Runner（标签 `axiomruntime-prod`）部署到 `154.201.73.41:/opt/AxiomRuntime`。部署只操作 `axiomruntime` Compose 项目；健康检查失败时恢复上一镜像，不清理服务器上的其他容器或镜像。
+
+首次部署前，服务器必须已有 `/opt/AxiomRuntime/config/providers.json` 和 `/opt/AxiomRuntime/secrets/server-token`，且容器用户 `10001:10001` 可以读写配置目录。CI 只校验这些文件，不生成或覆盖凭据。
+
+Telegram 容器默认不启动，以免与现有 long polling 进程争抢消息。完成迁移并停止旧 Bot 后，在服务器 `/opt/AxiomRuntime/.env` 中设置：
+
+```dotenv
+COMPOSE_PROFILES=telegram
+```
+
+启用前还要把各 Bot 的 `defaultCwd` 改为容器内的 `/workspace/...`，对应宿主机 `/opt/AxiomRuntime/workspaces/...`。之后的自动部署会同时更新 Runtime API 和所有位于 `config/telegram/bots/*.json` 的 Telegram Bot。资源上限和工作目录可参考 `.env.server.example` 调整。
+
+## 本机注册 `ai` 命令
+
+```bash
+npm link
+```
+
+注册后可直接使用：
+
+```bash
+ai
+ai --version
+ai setup
+ai help
+ai provider add
+ai provider list
+ai provider edit
+ai provider delete
+ai telegram
+ai telegram list
+ai telegram start --bot ops
+ai telegram status --bot ops
+ai status
+ai log
+ai log --print
+ai context
+ai context --print
+ai session
+ai session list
+ai session clear
+ai report
+ai doctor
+```
+
+## 配置文件
+
+默认从全局配置目录读取：
+
+```text
+~/.ai-gateway/providers.json
+~/.ai-gateway/.ai-cache.json
+~/.ai-gateway/usage.json
+~/.ai-gateway/model-pricing.json
+~/.ai-gateway/sessions.json
+~/.ai-gateway/telegram.json
+~/.ai-gateway/telegram.sqlite
+~/.ai-gateway/telegram.log
+~/.ai-gateway/reports/
+~/.ai-gateway/exports/
+~/.ai-gateway/.ai-gateway.log
+```
+
+可通过 `AI_GATEWAY_HOME` 覆盖配置目录。
+
+`providers.json` 包含 provider 配置和 SecretStore 引用，不要提交到仓库。
+
+Telegram Bot 集成说明：
+
+- 多 Bot 使用 `ai telegram add <name>` 创建，并以统一的 `--bot <name>` 选择目标；例如 `ai telegram edit --bot ops`、`start|stop|status --bot ops`、`delete --bot ops`。裸 `ai telegram` 会先选操作再选 Bot，删除有二次确认；批量生命周期操作使用 `--all`。
+- `ai telegram config set <key> <value> --bot <name>` 只修改指定 Bot；旧位置参数写法继续兼容。
+- 如果本机不能直连 Telegram API，可设置 `ai telegram config set proxyUrl http://127.0.0.1:7890 --bot <name>`。
+- Bot 首次 `/start` 或 `/reset` 会先选择工作路径，再选择 Claude Code/Codex，并展示当前会话、provider 和模型卡片。
+- Bot 会记录选择过的工作路径；自定义路径会按 `~/输入名称` 创建或复用。
+- Telegram 默认命令菜单只保留 `/claude`、`/codex`、`/reset`、`/cwd` 和 `/help`；选择 CLI 后，会在当前 chat 的 `/` 菜单追加该 CLI 的 slash 命令映射。
+- Telegram 远程执行复用 AI Gateway 顶层 provider，不维护另一套 provider 配置。
+- Telegram Codex 执行会自动走本地 OpenAI 兼容代理记录 provider usage；`/usage` 有 provider cost 时直接展示，否则按 `model-pricing.json` 估算。
+
+更多命令用法见：
+
+- [docs/usage.md](./docs/usage.md)
+- [docs/USAGE.html](./docs/USAGE.html)

package/dist/cli/commands/add.js

@@ -0,0 +1,29 @@
+import { addProvider } from "../../core/providers/provider-service.js";
+import { getCachedModels, updateProvider } from "../../core/providers/provider-service.js";
+import { writeLog } from "../../core/logs/log-service.js";
+import { promptSelect, promptText } from "../prompts/prompt.js";
+export async function runAddCommand(args) {
+    const [nameArg, baseUrlArg, apiKeyArg] = args;
+    const interactive = !nameArg || !baseUrlArg || !apiKeyArg;
+    const name = nameArg ?? await promptText("Provider name");
+    const baseUrl = baseUrlArg ?? await promptText("Base URL");
+    const apiKey = apiKeyArg ?? await promptText("API key");
+    let provider = await addProvider({ name, baseUrl, apiKey });
+    if (interactive) {
+        const models = await getCachedModels(provider.name);
+        if (models.length) {
+            const model = await promptSelect("Select default model", models.map((item) => ({ label: item, value: item })));
+            provider = await updateProvider(provider.name, { model });
+        }
+    }
+    console.log(`Added provider: ${provider.name}`);
+    console.log(`Level: ${provider.level}`);
+    console.log(`Mode: ${provider.mode}`);
+    console.log(`Default model: ${provider.model || "(not detected)"}`);
+    await writeLog({
+        category: "provider",
+        action: "provider_add",
+        message: `Added provider: ${provider.name}`,
+        metadata: { provider: provider.name, baseUrl: provider.baseUrl, level: provider.level, model: provider.model || null }
+    });
+}

package/dist/cli/commands/context.js

@@ -0,0 +1,29 @@
+import { spawn } from "node:child_process";
+import { generateProjectContext } from "../../core/context/context-service.js";
+import { writeLog } from "../../core/logs/log-service.js";
+export async function runContextCommand(args) {
+    const shouldPrint = args.includes("--print");
+    const context = await generateProjectContext();
+    await writeLog({
+        category: "usage",
+        action: "context_generated",
+        message: `Generated project context: ${context.filePath}`,
+        metadata: { filePath: context.filePath, printed: shouldPrint }
+    });
+    if (shouldPrint) {
+        console.log(context.content);
+        return;
+    }
+    await openFile(context.filePath);
+    console.log(`Opened context file: ${context.filePath}`);
+}
+async function openFile(filePath) {
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", filePath] : [filePath];
+    await new Promise((resolve) => {
+        const child = spawn(opener, args, { stdio: "ignore", detached: true });
+        child.on("error", () => resolve());
+        child.on("close", () => resolve());
+        child.unref();
+    });
+}

package/dist/cli/commands/doctor.js

@@ -0,0 +1,62 @@
+import { runDeepDoctor, runDoctor } from "../../core/status/doctor-service.js";
+import { writeLog } from "../../core/logs/log-service.js";
+import { promptConfirm } from "../prompts/prompt.js";
+import { printTable } from "../output/table.js";
+export async function runDoctorCommand(args) {
+    const deep = args.includes("--deep");
+    const yes = args.includes("--yes");
+    const strict = args.includes("--strict");
+    const local = args.includes("--local") || args.includes("--no-network");
+    const fix = !args.includes("--no-fix");
+    const tool = readTool(args);
+    if (deep && local) {
+        throw new Error("`--deep` cannot be combined with `--local` or `--no-network`.");
+    }
+    const result = deep
+        ? await runDeep(yes, tool, fix)
+        : { items: await runDoctor({ fix, checkProviders: !local }), deepPerformed: false };
+    await writeLog({
+        category: "usage",
+        action: result.deepPerformed ? "doctor_deep" : "doctor",
+        message: `Doctor completed with ${result.items.length} item(s).`,
+        metadata: {
+            deep: result.deepPerformed,
+            tool: result.deepPerformed ? tool : null,
+            fix,
+            local,
+            fixed: result.items.filter((item) => item.fixed).length,
+            errors: result.items.filter((item) => item.status === "error").length,
+            warnings: result.items.filter((item) => item.status === "warn").length
+        }
+    });
+    printDoctorItems(result.items);
+    if (strict && result.items.some((item) => item.status === "error")) {
+        process.exitCode = 1;
+    }
+}
+async function runDeep(yes, tool, fix) {
+    if (!yes) {
+        const confirmed = await promptConfirm("`ai doctor --deep` may consume tokens. Continue?");
+        if (!confirmed) {
+            return { items: await runDoctor({ fix }), deepPerformed: false };
+        }
+    }
+    return { items: await runDeepDoctor(tool, { fix }), deepPerformed: true };
+}
+export function printDoctorItems(items) {
+    printTable(items.map((item) => ({
+        group: item.group,
+        status: item.fixed ? "fixed" : item.status,
+        message: item.message,
+        next: item.suggestion ?? ""
+    })));
+}
+function readTool(args) {
+    const inline = args.find((arg) => arg.startsWith("--tool="));
+    const index = args.indexOf("--tool");
+    const value = inline?.slice("--tool=".length) ?? (index >= 0 ? args[index + 1] : undefined) ?? "codex";
+    if (value !== "claude" && value !== "codex") {
+        throw new Error("`--tool` must be `claude` or `codex`.");
+    }
+    return value;
+}

package/dist/cli/commands/edit.js

@@ -0,0 +1,85 @@
+import { readCache } from "../../core/config/cache-store.js";
+import { writeLog } from "../../core/logs/log-service.js";
+import { deleteProvider, listProviders, updateProvider } from "../../core/providers/provider-service.js";
+import { promptConfirm, promptSelect, promptText } from "../prompts/prompt.js";
+export async function runProviderEditCommand(name) {
+    const providers = await listProviders();
+    if (!providers.length) {
+        console.log("No providers configured. Run `ai add` first.");
+        return;
+    }
+    const providerName = name ?? await selectProviderName(providers);
+    const provider = providers.find((item) => item.name === providerName);
+    if (!provider) {
+        throw new Error(`Provider not found: ${providerName}`);
+    }
+    const field = await promptSelect("Select field", [
+        { label: "name", value: "name" },
+        { label: "baseUrl", value: "baseUrl" },
+        { label: "apiKey", value: "apiKey" },
+        { label: "mode", value: "mode" },
+        { label: "level", value: "level" },
+        { label: "model", value: "model" }
+    ]);
+    const patch = await buildPatch(provider, providers, field);
+    const updated = await updateProvider(provider.name, patch);
+    console.log(`Updated provider: ${updated.name}`);
+    await writeLog({
+        category: "provider",
+        action: "provider_edit",
+        message: `Updated provider: ${updated.name}`,
+        metadata: { provider: provider.name, field, renamedTo: updated.name !== provider.name ? updated.name : undefined }
+    });
+}
+export async function runProviderDeleteCommand(name) {
+    const providers = await listProviders();
+    if (!providers.length) {
+        console.log("No providers configured. Run `ai add` first.");
+        return;
+    }
+    const providerName = name ?? await selectProviderName(providers);
+    const provider = providers.find((item) => item.name === providerName);
+    if (!provider) {
+        throw new Error(`Provider not found: ${providerName}`);
+    }
+    const confirmed = await promptConfirm(`Delete provider ${provider.name}?`, false);
+    if (!confirmed) {
+        console.log("Delete cancelled.");
+        return;
+    }
+    await deleteProvider(provider.name);
+    console.log(`Deleted provider: ${provider.name}`);
+    await writeLog({
+        category: "provider",
+        action: "provider_delete",
+        message: `Deleted provider: ${provider.name}`,
+        metadata: { provider: provider.name }
+    });
+}
+async function selectProviderName(providers) {
+    return promptSelect("Select provider", providers.map((provider) => ({ label: `${provider.name} (level ${provider.level})`, value: provider.name })));
+}
+async function buildPatch(provider, providers, field) {
+    if (field === "mode") {
+        const mode = await promptSelect("Select mode", [
+            { label: "auto", value: "auto" },
+            { label: "ask", value: "ask" }
+        ]);
+        return { mode };
+    }
+    if (field === "level") {
+        const level = await promptSelect("Select level", providers.map((item) => ({ label: `${item.level}${item.name === provider.name ? " (current)" : ` (${item.name})`}`, value: item.level })));
+        return { level };
+    }
+    if (field === "model") {
+        const cache = await readCache();
+        const models = cache.providers[provider.name]?.models ?? [];
+        if (!models.length) {
+            throw new Error("No cached models found. Run `ai status` first.");
+        }
+        const model = await promptSelect("Select model", models.map((model) => ({ label: model, value: model })));
+        return { model };
+    }
+    const value = await promptText(`New ${field}`, { defaultValue: provider[field] });
+    return { [field]: value };
+}

package/dist/cli/commands/help.js

@@ -0,0 +1,16 @@
+import { spawn } from "node:child_process";
+import { getUsageHtmlPath } from "../../core/config/paths.js";
+export async function runHelpCommand() {
+    const filePath = getUsageHtmlPath();
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", filePath] : [filePath];
+    await new Promise((resolve) => {
+        const child = spawn(opener, args, { stdio: "ignore", detached: true });
+        child.on("error", () => {
+            console.log(filePath);
+            resolve();
+        });
+        child.on("close", () => resolve());
+        child.unref();
+    });
+}

package/dist/cli/commands/list.js

@@ -0,0 +1,25 @@
+import { listProviders } from "../../core/providers/provider-service.js";
+import { maskSecret } from "../output/table.js";
+export async function runListCommand() {
+    const providers = await listProviders();
+    if (!providers.length) {
+        console.log("No providers configured. Run `ai add` first.");
+        return;
+    }
+    console.log(`AI Gateway Providers (${providers.length})`);
+    console.log("=".repeat(72));
+    providers.forEach((provider, index) => {
+        const isDefault = provider.level === 1;
+        const title = `${provider.name}${isDefault ? "  [default]" : ""}`;
+        const header = `${provider.level.toString().padStart(2, "0")}  ${title}`;
+        console.log(header);
+        console.log("-".repeat(Math.min(72, Math.max(24, header.length))));
+        console.log(`  Base URL  ${provider.baseUrl}`);
+        console.log(`  API Key   ${maskSecret(provider.apiKey)}`);
+        console.log(`  Mode      ${provider.mode}`);
+        console.log(`  Model     ${provider.model || "(none)"}`);
+        if (index < providers.length - 1) {
+            console.log("");
+        }
+    });
+}

package/dist/cli/commands/log.js

@@ -0,0 +1,63 @@
+import { spawn } from "node:child_process";
+import { ensureLogFile, readRecentLogs } from "../../core/logs/log-service.js";
+export async function runLogCommand(args) {
+    if (!args.includes("--print")) {
+        const filePath = await ensureLogFile();
+        await openFile(filePath);
+        console.log(`Opened log file: ${filePath}`);
+        return;
+    }
+    const printableArgs = args.filter((arg) => arg !== "--print");
+    const limit = parseLimit(printableArgs[0]);
+    const logs = await readRecentLogs(limit);
+    printLogs(logs);
+}
+async function openFile(filePath) {
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", filePath] : [filePath];
+    await new Promise((resolve) => {
+        const child = spawn(opener, args, { stdio: "ignore", detached: true });
+        child.on("error", () => resolve());
+        child.on("close", () => resolve());
+        child.unref();
+    });
+}
+function parseLimit(value) {
+    if (!value)
+        return 50;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        return 50;
+    }
+    return Math.min(parsed, 500);
+}
+function printLogs(logs) {
+    if (!logs.length) {
+        console.log("No logs found.");
+        return;
+    }
+    console.log(`AI Gateway Logs (${logs.length})`);
+    console.log("=".repeat(88));
+    logs.forEach((event, index) => {
+        const badge = formatBadge(event.level);
+        console.log(`${index + 1}. ${badge} ${event.timestamp}`);
+        console.log(`   ${event.category} / ${event.action}`);
+        console.log(`   ${event.message}`);
+        if (event.metadata && Object.keys(event.metadata).length) {
+            console.log(`   metadata: ${formatMetadata(event.metadata)}`);
+        }
+        if (index < logs.length - 1) {
+            console.log("-".repeat(88));
+        }
+    });
+}
+function formatBadge(level) {
+    if (level === "error")
+        return "[ERROR]";
+    if (level === "warn")
+        return "[WARN ]";
+    return "[INFO ]";
+}
+function formatMetadata(metadata) {
+    return JSON.stringify(metadata);
+}