@jpssff/vanor 0.1.0

package/README-cn.md

@@ -0,0 +1,166 @@
+# Vanor（万佑）
+
+万佑智算通用 CLI 智能体。Vanor 由大模型驱动，可在本地工作区内理解任务、规划步骤、读写文件、执行命令，并通过会话、记忆、技能和安全审批机制持续协助开发者工作。
+
+## 快速开始
+
+```bash
+npm i -g @jpssff/vanor
+vanor config
+vanor
+```
+
+要求 Node.js `>=18`。当前版本保持零第三方运行时依赖，仅使用 Node.js 原生模块。
+
+配置文件位于 `~/.vanor/config.json`。`apiKey` 推荐使用 `env:VAR_NAME` 引用环境变量，避免明文写入配置：
+
+```jsonc
+{
+  "llm": {
+    "defaultModel": "wanyou/deepseek/deepseek-v4-pro",
+    "providers": {
+      "wanyou": {
+        "type": "openai",
+        "baseURL": "https://wanyouzhisuan.com/api/v1",
+        "apiKey": "env:VANOR_API_KEY",
+        "models": ["deepseek/deepseek-v4-pro", "deepseek/deepseek-v4-flash"]
+      }
+    },
+    "fallback": []
+  },
+  "security": {
+    "approval": "ask",
+    "workspaceRoot": "."
+  },
+  "ui": {
+    "language": "auto"
+  }
+}
+```
+
+`ui.language` 支持 `auto`、`en`、`zh-CN`。`auto` 会根据操作系统 / 终端语言自动切换，无法确认时默认英文；交互中可用 `/language` 查看或切换语言。
+
+## 核心能力
+
+- **交互式 CLI**：彩色流式输出、固定输入行、底部状态栏、上下文用量、模型、工作区和运行状态动画。
+- **Agent Loop**：LLM ↔ 工具迭代，支持文件读写、命令执行、记忆和技能工具。
+- **安全执行**：默认危险操作需确认；支持 allowlist / denylist；`/auto-run` 只在当前会话临时减少确认，denylist 仍生效。
+- **会话恢复**：会话以 JSONL 存储；`~/.vanor/state.json` 按 `workspaceRoot` 记录最近 session，切换工作区后可恢复各自上下文。
+- **上下文压缩**：接近上下文窗口时自动压缩；也可用 `/compact` 手动压缩。
+- **配置热重载**：交互过程中修改 `config.json` 后，下一轮自动重载；也可执行 `/reload`。
+- **模型切换**：`/model <关键词>` 会搜索当前模型、默认模型、fallback 和 provider `models` 列表，多个命中时编号选择。
+- **多语言**：自动检测系统语言，支持英文和简体中文；可用 `/language [auto|en|zh-CN]` 即时切换并写回配置。
+- **技能系统**：自动扫描本机和工作区 skills，注入请求上下文；支持读取、创建、修改、删除本地 `SKILL.md`。
+- **可观测日志**：JSONL 事件日志；可选开启完整 LLM 请求 / 响应 trace，并默认脱敏敏感 header。
+
+## CLI 命令
+
+```text
+vanor              # 交互对话
+vanor config       # 配置 LLM provider 与默认模型
+vanor doctor       # 检查配置
+vanor sessions     # 查看历史会话
+vanor resume [id]  # 恢复指定或最近会话
+vanor skills       # 列出已加载技能
+```
+
+交互内 slash 命令：
+
+```text
+/help            显示帮助
+/new             开启新会话
+/messages        查看当前会话的历史用户消息
+/compact         立即压缩上下文
+/retry           重发上一条消息
+/model [关键词]  查看或搜索切换模型
+/language [语言] 查看或切换语言（auto | en | zh-CN）
+/usage           查看本会话 token 用量
+/skills          列出已加载技能
+/reload          立即重载配置文件
+/auto-run [off]  本次对话自动执行操作，不再逐次确认（off 恢复）
+/exit            退出
+```
+
+## 目录结构
+
+```text
+vanor/                       # npm 包（只读）
+├── index.js                 # CLI 入口
+├── base/
+│   ├── core/                # harness、loop、session、prompt、compaction
+│   ├── llm/                 # provider 抽象与调用
+│   ├── tools/               # 工具注册、审批、执行
+│   ├── skills/loader.js     # 技能加载与管理
+│   ├── memory/              # 长期 / 工作记忆
+│   ├── transport/           # CLI 与统一 Message 协议
+│   ├── security/            # 工作区边界、allowlist、denylist
+│   ├── events.js
+│   ├── logger.js
+│   ├── config.js
+│   └── test/                # node:test 契约测试
+└── docs/
+
+~/.vanor/                    # 运行时根目录（可写）
+├── config.json              # 配置
+├── state.json               # 工作区最近 session 索引
+├── skills/                  # 用户技能
+├── memory/
+│   ├── MEMORY.md            # 长期：环境事实
+│   ├── USER.md              # 长期：用户偏好
+│   └── working/             # 工作记忆
+├── sessions/                # 会话 JSONL，每会话一文件
+├── cache/
+└── logs/                    # JSONL 日志
+```
+
+## 技能加载
+
+Vanor 会从以下位置加载技能，工作区技能优先：
+
+- 当前工作区 `.skills/`
+- 当前工作区 `skills/`
+- `~/.vanor/skills`
+- `~/.cursor/skills-cursor`
+- `~/.claude/skills`
+- `~/.agents/skills`
+- `~/.codex/skills`
+- `~/.codex/skills/.archive`
+
+每个技能通常是一个包含 frontmatter 的 `SKILL.md`。Vanor 能解析常见 YAML description 写法，包括单行、folded block（`>-`）和 literal block（`|`）。
+
+## 记忆与会话
+
+Vanor 使用三层记忆：
+
+| 层级 | 说明 |
+|------|------|
+| 短期 | 当前会话消息，存于 `sessions/`；压缩后内存只保留摘要与最近消息，但磁盘保留完整历史 |
+| 长期 | `memory/MEMORY.md` 与 `memory/USER.md`，记录环境事实和用户偏好 |
+| 工作 | `memory/working/`，保存任务中的计划和中间状态 |
+
+会话恢复优先读取 `state.json` 中当前工作区的最近 session id，避免 session 文件过多时启动扫描变慢。若索引失效，再回退扫描 `sessions/`。
+
+## 日志与 LLM Trace
+
+默认只记录结构化事件日志。需要排查 provider 请求时，可开启完整 LLM trace：
+
+```jsonc
+{
+  "logging": {
+    "level": "info",
+    "llmTrace": true,
+    "llmTraceRedact": true
+  }
+}
+```
+
+开启后会记录请求 URL、headers、body、响应内容等详细信息；`llmTraceRedact` 默认开启，会脱敏 `Authorization`、`api-key` 等敏感 header。
+
+## 设计原则
+
+- 零运行时依赖，优先使用 Node.js 原生能力。
+- 模块职责清晰：Transport / Core / Loop / Tools / Skills / Memory / Security 解耦。
+- 默认安全：工作区边界、危险命令确认、denylist 拦截。
+- 所有关键状态可恢复、可观测、可测试。
+
+详细技术设计见 [docs/TECH_DESIGN.md](docs/TECH_DESIGN.md)。

package/README.md

@@ -0,0 +1,120 @@
+# Vanor
+
+Vanor is a zero-dependency CLI agent for developers. It uses your LLM provider to understand tasks, edit files, run commands, keep session history, and work safely inside your local workspace.
+
+中文文档：[README-cn.md](README-cn.md)
+
+## Install
+
+```bash
+npm i -g @jpssff/vanor
+```
+
+Requires Node.js `>=18`.
+
+## Quick Start
+
+Configure your model provider:
+
+```bash
+vanor config
+```
+
+Start chatting in your project:
+
+```bash
+cd your-project
+vanor
+```
+
+Vanor stores config and runtime data under `~/.vanor/`.
+
+## Manual Config
+
+You can edit `~/.vanor/config.json` directly. Use `env:VAR_NAME` for API keys so secrets are not stored in plain text.
+
+```jsonc
+{
+  "llm": {
+    "defaultModel": "wanyou/deepseek/deepseek-v4-pro",
+    "providers": {
+      "wanyou": {
+        "type": "openai",
+        "baseURL": "https://wanyouzhisuan.com/api/v1",
+        "apiKey": "env:VANOR_API_KEY",
+        "models": ["deepseek/deepseek-v4-pro", "deepseek/deepseek-v4-flash"]
+      }
+    },
+    "fallback": []
+  },
+  "security": {
+    "approval": "ask",
+    "workspaceRoot": "."
+  },
+  "ui": {
+    "language": "auto"
+  }
+}
+```
+
+Config changes are hot-reloaded before the next turn. You can also run `/reload` inside Vanor.
+`ui.language` can be `auto`, `en`, or `zh-CN`. In `auto` mode, Vanor detects your OS / terminal language and falls back to English when unsure. You can switch it inside the chat with `/language`.
+
+## Common Commands
+
+```bash
+vanor              # start interactive chat
+vanor config       # configure provider and model
+vanor doctor       # check configuration
+vanor sessions     # list sessions
+vanor resume [id]  # resume a session
+vanor skills       # list loaded skills
+```
+
+Inside the chat:
+
+```text
+/help            show help
+/new             start a new session
+/messages        list user messages in the current session
+/compact         compact context now
+/retry           retry the last message
+/model [query]   show or search and switch models
+/language [lang] show or switch language
+/usage           show token usage
+/skills          list loaded skills
+/reload          reload config
+/auto-run [off]  auto-approve actions for this session
+/exit            quit
+```
+
+## Highlights
+
+- Interactive terminal UI with streaming output, a fixed input line, and a live status bar.
+- Workspace-aware session restore, so each project resumes its own latest session.
+- File and command tools with confirmation, allowlist / denylist, and workspace boundaries.
+- Skills are loaded automatically from `~/.vanor/skills`, common local skill folders, and workspace `.skills/` or `skills/`.
+- Optional full LLM request / response tracing for debugging, with sensitive headers redacted by default.
+
+## Safety
+
+Vanor asks before potentially risky tool actions by default. `/auto-run` only changes approval behavior for the current session, and denylisted commands are still blocked.
+
+## Data Locations
+
+```text
+~/.vanor/config.json   provider, model, security, logging config
+~/.vanor/state.json    latest session index per workspace
+~/.vanor/sessions/     JSONL session history
+~/.vanor/memory/       long-term and working memory
+~/.vanor/skills/       user skills
+~/.vanor/logs/         JSONL logs
+```
+
+## Development
+
+```bash
+npm test
+```
+
+Design details: [docs/TECH_DESIGN.md](docs/TECH_DESIGN.md).

package/base/config.js

@@ -0,0 +1,162 @@
+// 配置加载与校验。顺序：内置默认 → ~/.vanor/config.json → 环境变量覆盖。
+
+import fs from "node:fs";
+import path from "node:path";
+import { homedir } from "node:os";
+import { createI18n, isSupportedLanguageSetting } from "./i18n/index.js";
+import { deepMerge, ensureDir, expandHome, isPlainObject, readJsonSafe } from "./utils.js";
+
+const fallbackT = createI18n("en").t;
+
+export const DEFAULT_CONFIG = {
+  llm: {
+    defaultModel: "",
+    providers: {},
+    fallback: [],
+  },
+  agent: {
+    maxIterations: 25,
+    thinking: "off",
+    contextWindow: 256000,
+  },
+  memory: {
+    memoryMaxChars: 2200,
+    userMaxChars: 1375,
+    compactThreshold: 0.75,
+  },
+  security: {
+    approval: "ask", // ask | auto | deny
+    allowlist: [],
+    denylist: ["rm -rf *", "sudo *", "shutdown *", "mkfs *"],
+    workspaceRoot: ".",
+    allowOutsideWorkspace: false,
+  },
+  session: {
+    restore: "last", // last | none
+    reset: { idleMinutes: 0, daily: false },
+    dmScope: "main",
+  },
+  logging: {
+    level: "info",
+    llmTrace: false, // 记录每次 LLM 请求/响应的完整详情（url、headers、body、返回内容）
+    llmTraceRedact: true, // 记录时对 Authorization / api-key 等敏感 header 脱敏
+  },
+  ui: {
+    color: true,
+    stream: true,
+    language: "auto", // auto | en | zh-CN
+  },
+};
+
+/** 返回 ~/.vanor 下的标准路径集合。 */
+export function getPaths(root) {
+  const base = root || path.join(homedir(), ".vanor");
+  return {
+    root: base,
+    config: path.join(base, "config.json"),
+    state: path.join(base, "state.json"),
+    skills: path.join(base, "skills"),
+    memory: path.join(base, "memory"),
+    working: path.join(base, "memory", "working"),
+    sessions: path.join(base, "sessions"),
+    cache: path.join(base, "cache"),
+    logs: path.join(base, "logs"),
+    baseUser: path.join(base, "base-user"),
+    backups: path.join(base, "backups"),
+    plugins: path.join(base, "plugins"),
+  };
+}
+
+/** 确保运行时目录存在。 */
+export function ensurePaths(paths) {
+  for (const key of ["root", "skills", "memory", "working", "sessions", "cache", "logs"]) {
+    ensureDir(paths[key]);
+  }
+}
+
+/** 递归解析 "env:VAR" 形式的字符串为环境变量值。 */
+function resolveEnv(value) {
+  if (typeof value === "string") {
+    return value.startsWith("env:") ? process.env[value.slice(4)] || "" : value;
+  }
+  if (Array.isArray(value)) return value.map(resolveEnv);
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = resolveEnv(v);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * 加载配置。
+ * @param {string} [configPath] 配置文件路径，默认 ~/.vanor/config.json
+ * @returns {{ config: object, exists: boolean, path: string }}
+ */
+export function loadConfig(configPath) {
+  const file = configPath || getPaths().config;
+  const exists = fs.existsSync(file);
+  const fileConfig = exists ? readJsonSafe(file, {}) : {};
+  const merged = deepMerge(DEFAULT_CONFIG, fileConfig || {});
+  const config = resolveEnv(merged);
+  // workspaceRoot 归一为绝对路径（仅作用于运行时 config；raw 保留原始值供回写）
+  config.security.workspaceRoot = path.resolve(expandHome(config.security.workspaceRoot || "."));
+  // raw：未解析 env、未绝对化的合并结果，供配置向导回写，避免破坏 env: 引用
+  return { config, raw: merged, exists, path: file };
+}
+
+/** 写入配置文件（保留 env: 占位，不写入解析后的密钥）。 */
+export function saveConfig(configPath, config) {
+  const file = configPath || getPaths().config;
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, JSON.stringify(config, null, 2));
+  return file;
+}
+
+/** 仅写回 ui.language，保留 raw config 中的 env: 引用。 */
+export function saveUiLanguage(configPath, language) {
+  const file = configPath || getPaths().config;
+  const raw = fs.existsSync(file) ? readJsonSafe(file, {}) || {} : {};
+  raw.ui = raw.ui || {};
+  raw.ui.language = language;
+  return saveConfig(file, raw);
+}
+
+/** 基本合法性校验，返回问题列表（供 vanor doctor 使用）。 */
+export function validateConfig(config, t = fallbackT) {
+  const issues = [];
+  if (!config.llm?.defaultModel) issues.push(t("config.errors.noDefaultModel"));
+  const providers = config.llm?.providers || {};
+  if (Object.keys(providers).length === 0) issues.push(t("config.errors.noProviders"));
+  for (const [name, p] of Object.entries(providers)) {
+    if (!p.baseURL && p.type !== "anthropic") issues.push(t("config.errors.providerMissingBaseURL", { name }));
+    if (!p.apiKey) issues.push(t("config.errors.providerMissingApiKey", { name }));
+  }
+  if (!["ask", "auto", "deny"].includes(config.security?.approval)) {
+    issues.push(t("config.errors.approvalInvalid"));
+  }
+  if (!isSupportedLanguageSetting(config.ui?.language || "auto")) {
+    issues.push(t("config.errors.languageInvalid"));
+  }
+  return issues;
+}
+
+/**
+ * 仅校验启动所必需的项：默认模型及其引用的 provider。
+ * 不波及其它未使用的 provider（避免残留/备用配置阻塞启动）。
+ */
+export function startupIssues(config, t = fallbackT) {
+  const model = config.llm?.defaultModel;
+  if (!model) return [t("config.errors.noDefaultModel")];
+  const slash = model.indexOf("/");
+  if (slash < 0) return [t("config.errors.defaultModelFormat", { model })];
+  const name = model.slice(0, slash);
+  const p = config.llm?.providers?.[name];
+  if (!p) return [t("config.errors.defaultProviderMissing", { name })];
+  const issues = [];
+  if (!p.apiKey) issues.push(t("config.errors.providerMissingApiKey", { name }));
+  if ((p.type || "openai") !== "anthropic" && !p.baseURL) {
+    issues.push(t("config.errors.providerMissingBaseURL", { name }));
+  }
+  return issues;
+}

package/base/core/compaction.js

@@ -0,0 +1,58 @@
+// 上下文压缩：历史超阈值时摘要旧消息，保留最近若干轮。
+
+import { EVENTS } from "../events.js";
+import { systemMessage, userMessage } from "../transport/message.js";
+
+const KEEP_RECENT = 6;
+
+/** 估算上下文是否超过压缩阈值。 */
+export function shouldCompact(session, config) {
+  const window = config.agent?.contextWindow ?? 256000;
+  const threshold = config.memory?.compactThreshold ?? 0.75;
+  return session.estimatedTokens() > window * threshold;
+}
+
+/**
+ * 压缩较旧的消息为摘要，保留最近的对话。
+ * recent 从最近的一条 user 消息开始，保证发往 provider 的序列合法。
+ */
+export async function compact(session, deps) {
+  const msgs = session.messages;
+  if (msgs.length <= KEEP_RECENT + 2) return;
+
+  let idx = msgs.length - KEEP_RECENT;
+  while (idx > 0 && msgs[idx].role !== "user") idx--;
+  if (idx <= 0) return; // 找不到安全切点，放弃本次压缩
+
+  const older = msgs.slice(0, idx);
+  const recent = msgs.slice(idx);
+
+  const convo = older
+    .map((m) => {
+      const tools = m.toolCalls?.length ? ` [调用:${m.toolCalls.map((t) => t.name).join(",")}]` : "";
+      return `${m.role}: ${(m.content || "").slice(0, 2000)}${tools}`;
+    })
+    .join("\n");
+
+  let summaryText = "";
+  try {
+    const res = await deps.llm.gather({
+      model: deps.model,
+      messages: [
+        systemMessage(
+          "你是对话压缩器。用简洁中文总结以下历史，保留关键事实、文件路径、已完成项与待办，省略寒暄与冗余。",
+        ),
+        userMessage(convo),
+      ],
+    });
+    summaryText = res.text || "";
+  } catch (e) {
+    deps.logger?.warn(EVENTS.memory.compress, { error: e.message, skipped: true });
+    return; // 压缩失败则保持原样
+  }
+
+  session.summary = session.summary ? `${session.summary}\n${summaryText}` : summaryText;
+  session.replaceRecent(recent);
+  session.addCompaction({ summary: summaryText, replaced: older.length });
+  deps.logger?.info(EVENTS.memory.compress, { replaced: older.length });
+}