@apolloyh/apollo-agent 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,202 @@
+export type JsonObject = Record<string, unknown>;
+export type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: JsonObject;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+};
+export type Message = {
+    role: "user" | "assistant";
+    content: string | ContentBlock[];
+};
+export type AnthropicTool = {
+    name: string;
+    description: string;
+    input_schema: JsonObject;
+};
+export type ToolRisk = "low" | "medium" | "high";
+export type ToolDefinition = AnthropicTool & {
+    risk: ToolRisk;
+    execute(input: JsonObject, context: ToolExecutionContext): Promise<ToolResult>;
+};
+export type ToolResult = {
+    content: string;
+    isError?: boolean;
+    fileChange?: FileChangeDisplay;
+};
+export type FileChangeDisplay = {
+    path: string;
+    kind: "create" | "update";
+    added: number;
+    removed: number;
+    lines: string[];
+    omitted: number;
+};
+/** Claude Code–style Task / subagent lifecycle events. */
+export type TraceEvent = {
+    type: "llm_request";
+    turn: number;
+    toolCount: number;
+} | {
+    type: "llm_retry";
+    attempt: number;
+    reason: string;
+    mode: "same-request" | "non-stream" | "after-compaction" | "continue";
+    delayMs?: number;
+} | {
+    type: "llm_response";
+    turn: number;
+    stopReason?: string;
+    text?: string;
+} | {
+    type: "assistant_delta";
+    text: string;
+} | {
+    type: "llm_tool_delta";
+    bytes: number;
+    tool?: string;
+    detail?: string;
+} | {
+    type: "tool_call";
+    tool: string;
+    input: JsonObject;
+    risk: ToolRisk;
+} | {
+    type: "tool_result";
+    tool: string;
+    input?: JsonObject;
+    isError?: boolean;
+    content: string;
+    fileChange?: FileChangeDisplay;
+} | {
+    type: "approval_required";
+    tool: string;
+    risk: ToolRisk;
+    reason: string;
+} | {
+    type: "approval_result";
+    tool: string;
+    approved: boolean;
+} | {
+    type: "context_compaction_start";
+    beforeChars: number;
+} | {
+    type: "context_compacted";
+    beforeChars: number;
+    afterChars: number;
+} | {
+    type: "context_compaction_failed";
+    reason: string;
+} | {
+    type: "task_start";
+    id: string;
+    subagentType: string;
+    description: string;
+} | {
+    type: "task_progress";
+    id: string;
+    subagentType: string;
+    message: string;
+} | {
+    type: "task_finish";
+    id: string;
+    subagentType: string;
+    description: string;
+    result: string;
+    durationMs: number;
+} | {
+    type: "workflow_status";
+    goal: string;
+    phases: Array<{
+        name: string;
+        label: string;
+        status: string;
+        summary?: string;
+    }>;
+} | {
+    type: "plan_mode";
+    active: boolean;
+    approved?: boolean;
+    path?: string;
+} | {
+    type: "user_question";
+    question: string;
+    options?: string[];
+} | {
+    type: "user_answer";
+    answer: string;
+} | {
+    type: "goal_status";
+    goal: string;
+    status: string;
+    iteration: number;
+    maxIterations: number;
+    progress: string[];
+};
+export type TraceSink = (event: TraceEvent) => void;
+export type ApprovalRequest = {
+    toolName: string;
+    risk: ToolRisk;
+    reason: string;
+    input: JsonObject;
+};
+export type ApprovalProvider = (request: ApprovalRequest) => Promise<boolean>;
+export type AskUserFn = (question: string, options?: string[]) => Promise<string>;
+export type ToolExecutionContext = {
+    workspaceRoot: string;
+    emit: TraceSink;
+    requestApproval: ApprovalProvider;
+    signal?: AbortSignal;
+    /** Structured user question (AskUserQuestion) */
+    askUser?: AskUserFn;
+    /** When true, write tools are restricted (plan mode) */
+    planMode?: boolean;
+};
+export type LlmConfig = {
+    authToken: string;
+    baseUrl: string;
+    model: string;
+    maxTokens: number;
+    timeoutMs?: number;
+    cacheTtl?: "5m" | "1h";
+};
+export type McpServerConfig = {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+};
+export type SubagentConfig = {
+    name: string;
+    description: string;
+    tools?: string[];
+    prompt: string;
+};
+export type AgentConfig = {
+    workspaceRoot: string;
+    maxTurns: number;
+    systemPrompt?: string;
+    modeInstructions?: string;
+    context: {
+        maxChars: number;
+        summaryChars: number;
+    };
+    permissions: {
+        mode: "ask" | "readonly" | "unrestricted";
+        autoApproveReadOnly: boolean;
+    };
+    skills: {
+        directories: string[];
+    };
+    mcpServers: Record<string, McpServerConfig>;
+    agents: SubagentConfig[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,8 @@
+export declare function truncate(value: string, max?: number): string;
+export declare function truncateMiddle(value: string, max?: number): string;
+export declare function stringify(value: unknown, max?: number): string;
+export declare function safeResolve(root: string, target: string): string;
+export declare function safeRealResolve(root: string, target: string): Promise<string>;
+export declare function messageText(content: unknown): string;
+export declare function estimateChars(value: unknown): number;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAGA,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAO,GAAG,MAAM,CAG1D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAQ,GAAG,MAAM,CAQjE;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,SAAO,GAAG,MAAM,CAG5D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAOhE;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6BnF;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAQpD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD"}

package/dist/utils.js

@@ -0,0 +1,78 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export function truncate(value, max = 4000) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max)}\n...[truncated ${value.length - max} chars]`;
+}
+export function truncateMiddle(value, max = 30000) {
+    if (value.length <= max)
+        return value;
+    const marker = "\n...[tool result truncated]...\n";
+    if (max <= marker.length)
+        return value.slice(0, max);
+    const available = max - marker.length;
+    const headLength = Math.ceil(available * 0.6);
+    const tailLength = available - headLength;
+    return `${value.slice(0, headLength)}${marker}${tailLength > 0 ? value.slice(-tailLength) : ""}`;
+}
+export function stringify(value, max = 6000) {
+    const text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+    return truncate(text, max);
+}
+export function safeResolve(root, target) {
+    const resolved = path.resolve(root, target);
+    const normalizedRoot = path.resolve(root);
+    if (resolved !== normalizedRoot && !resolved.startsWith(`${normalizedRoot}${path.sep}`)) {
+        throw new Error(`Path escapes workspace: ${target}`);
+    }
+    return resolved;
+}
+export async function safeRealResolve(root, target) {
+    const resolved = safeResolve(root, target);
+    const realRoot = await fs.realpath(path.resolve(root));
+    const missingSegments = [];
+    let probe = resolved;
+    for (;;) {
+        try {
+            const realProbe = await fs.realpath(probe);
+            const relative = path.relative(realRoot, realProbe);
+            if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+                throw new Error(`Path escapes workspace: ${target} -> ${realProbe}`);
+            }
+            return path.join(realProbe, ...missingSegments);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            try {
+                if ((await fs.lstat(probe)).isSymbolicLink()) {
+                    throw new Error(`Path escapes workspace: ${target}`);
+                }
+            }
+            catch (lstatError) {
+                if (lstatError.code !== "ENOENT")
+                    throw lstatError;
+            }
+            const parent = path.dirname(probe);
+            if (parent === probe)
+                throw error;
+            missingSegments.unshift(path.basename(probe));
+            probe = parent;
+        }
+    }
+}
+export function messageText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((block) => block && typeof block === "object" && block.type === "text")
+        .map((block) => block.text)
+        .filter((text) => typeof text === "string")
+        .join("\n");
+}
+export function estimateChars(value) {
+    return JSON.stringify(value).length;
+}

package/docs/sdk.md

@@ -0,0 +1,259 @@
+# Apollo SDK 接入指南
+
+Apollo SDK 用于把 Agent 能力嵌入 Node.js / TypeScript 系统。CLI 只是终端界面；SDK 与 CLI 使用同一个 `QueryEngine`、工具、权限、会话、记忆和 Prompt Cache 机制。
+
+## 运行要求
+
+- Node.js 20 或更高版本
+- ESM 项目（`import`，不提供 CommonJS `require`）
+- Anthropic Messages API 兼容模型服务
+
+## 安装
+
+当前使用本地 tarball：
+
+```bash
+npm install /Users/apollo/Code-YH/web-agent/agent/apolloyh-apollo-agent-0.1.0.tgz
+```
+
+发布到 npm 后可改为：
+
+```bash
+npm install @apolloyh/apollo-agent
+```
+
+## 长期对话
+
+一个 `QueryEngine` 对应一个对话。重复调用 `submitMessage()` 会保留历史、会话状态和缓存稳定前缀。
+
+```ts
+import { createQueryEngine } from "@apolloyh/apollo-agent";
+
+const engine = await createQueryEngine({
+  configPath: ".apollo/config.json",
+  envPath: ".apollo/.env",
+  onEvent(event) {
+    if (event.type === "assistant_delta") {
+      process.stdout.write(event.text);
+    }
+  },
+});
+
+try {
+  await engine.submitMessage("分析这个项目");
+  await engine.submitMessage("继续修复发现的问题");
+} finally {
+  await engine.close();
+}
+```
+
+必须调用 `close()`，它会关闭当前 Engine 持有的 MCP 连接。不要并发调用同一个 Engine 的 `submitMessage()`；每个独立对话使用独立 Engine。
+
+## 一次性调用
+
+`runAgentTurn()` 创建临时 Engine，执行一次用户请求并自动关闭。一次请求内部仍可包含多轮模型与工具调用。
+
+```ts
+import { runAgentTurn } from "@apolloyh/apollo-agent";
+
+const result = await runAgentTurn({
+  input: "审查这个项目",
+  configPath: ".apollo/config.json",
+  envPath: ".apollo/.env",
+});
+
+console.log(result.text);
+```
+
+## 服务端推荐配置
+
+`envPath` 会把文件内容加载到进程级 `process.env`。单用户应用可以使用；多租户服务应直接传入每个 Engine 的 `llmConfig`，避免不同租户共享环境变量。
+
+```ts
+const engine = await createQueryEngine({
+  configPath: tenant.configPath,
+  llmConfig: {
+    authToken: tenant.modelApiKey,
+    baseUrl: "https://open.bigmodel.cn/api/anthropic",
+    model: "glm-5.2",
+    maxTokens: 4096,
+    timeoutMs: 300_000,
+    cacheTtl: "5m",
+  },
+});
+```
+
+不要把 API Key 写入 `.apollo/config.json`、日志或会话消息。
+
+## `createQueryEngine()` 参数
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `configPath` | `string` | Agent 配置路径；默认发现 `.apollo/config.json`，兼容旧 `agent.config.json` |
+| `envPath` | `string` | 可选环境变量文件；未提供模型配置时默认发现 `.apollo/.env`，然后 `.env` |
+| `agentConfig` | `AgentConfig` | 直接传入完整 Agent 配置；优先于 `configPath` |
+| `llmConfig` | `LlmConfig` | 直接传入模型配置；优先于环境变量 |
+| `onEvent` | `(event) => void` | 接收流式文本、工具、审批、子 Agent 和压缩事件 |
+| `approvalProvider` | `async (request) => boolean` | 接入宿主系统权限审批 |
+| `askUser` | `async (question, options?) => string` | 接入宿主系统问答 UI |
+| `assumeYes` | `boolean \| (() => boolean)` | 使用默认审批器时自动批准；服务端不建议启用 |
+| `stream` | `boolean \| (() => boolean)` | 是否使用模型流式响应，默认开启 |
+| `sessionId` | `string` | 创建后立即恢复指定会话 |
+
+如果同时传入 `agentConfig` 和 `configPath`，使用 `agentConfig`；如果同时传入 `llmConfig` 和环境变量，使用 `llmConfig`。
+
+## 系统提示词与缓存
+
+`.apollo/config.json` 可以配置：
+
+```json
+{
+  "systemPrompt": "你是当前产品的项目 Agent。始终使用中文回答。"
+}
+```
+
+Engine 创建时读取配置，首次请求时拼接 System Prompt 和工具定义，随后在该 Engine 生命周期内冻结。修改配置文件不会影响已经存在的 Engine，必须关闭并创建新 Engine。
+
+运行中主要变化的是 `messages`，接近上下文上限时会执行语义压缩；稳定的 `system` 和 `tools` 有利于命中模型厂商的 Prompt Cache。
+
+## 流式事件
+
+```ts
+const engine = await createQueryEngine({
+  configPath: ".apollo/config.json",
+  llmConfig,
+  onEvent(event) {
+    switch (event.type) {
+      case "assistant_delta":
+        websocket.send(JSON.stringify({ type: "text", text: event.text }));
+        break;
+      case "tool_call":
+        websocket.send(JSON.stringify({ type: "tool", name: event.tool, risk: event.risk }));
+        break;
+      case "task_progress":
+        websocket.send(JSON.stringify({ type: "task", message: event.message }));
+        break;
+    }
+  },
+});
+```
+
+常用事件：
+
+| 事件 | 用途 |
+|---|---|
+| `assistant_delta` | 流式回答文本 |
+| `llm_request` / `llm_response` | 模型请求生命周期 |
+| `llm_retry` | 自动重试或流式降级 |
+| `tool_call` / `tool_result` | 工具执行状态 |
+| `approval_required` / `approval_result` | 默认审批器状态 |
+| `task_start` / `task_progress` / `task_finish` | 子 Agent 状态 |
+| `context_compaction_start` / `context_compacted` | 上下文压缩状态 |
+| `goal_status` / `workflow_status` / `plan_mode` | 运行模式状态 |
+
+`onEvent` 可能包含工具参数或结果。转发到日志和前端前，应按宿主系统的数据策略脱敏。
+成功的 `write_file` 事件还会携带 `fileChange`，用于渲染新文件预览或彩色 diff；该字段不会发送给模型。
+
+## 权限审批
+
+自定义 `approvalProvider` 会接收每次工具调用。宿主系统应根据用户、工作区、工具和风险等级决定是否允许。
+
+```ts
+const engine = await createQueryEngine({
+  configPath: ".apollo/config.json",
+  llmConfig,
+  approvalProvider: async (request) => {
+    if (request.risk === "low") return true;
+    return await permissions.askCurrentUser({
+      tool: request.toolName,
+      risk: request.risk,
+      reason: request.reason,
+      input: request.input,
+    });
+  },
+});
+```
+
+SDK 的权限边界属于应用层，不是操作系统沙箱。允许 `shell_exec` 或 MCP 后，进程仍拥有当前操作系统用户的权限。多租户或不可信用户场景需要额外使用容器或独立进程隔离。
+
+## 用户提问
+
+```ts
+const engine = await createQueryEngine({
+  configPath: ".apollo/config.json",
+  llmConfig,
+  askUser: async (question, options) => {
+    return await ui.waitForAnswer({ question, options });
+  },
+});
+```
+
+没有提供 `askUser` 时，Agent 会收到当前环境无法进行交互式提问的错误结果，并改为在最终回答中询问。
+
+## 会话恢复
+
+CLI 与 CC 一样支持 `apollo -c` 继续当前项目最近会话，以及 `apollo -r [session-id]` 选择或恢复指定会话。交互模式也可以使用 `/sessions` 和 `/resume [session-id]`。省略 ID 时可用 ↑/↓ 选择会话、Enter 恢复；恢复后终端会重新显示可读的历史对话。
+
+```ts
+const first = await createQueryEngine({ configPath, llmConfig });
+await first.submitMessage("分析项目");
+const sessionId = first.getSessionId();
+await first.close();
+
+const resumed = await createQueryEngine({
+  configPath,
+  llmConfig,
+  sessionId: sessionId!,
+});
+
+try {
+  await resumed.submitMessage("继续");
+} finally {
+  await resumed.close();
+}
+```
+
+会话默认保存在项目的 `.apollo/sessions/`。会话内容没有加密，不应保存秘密。
+
+## 常用 Engine 方法
+
+| 方法 | 说明 |
+|---|---|
+| `submitMessage(input)` | 提交一条用户消息 |
+| `close()` | 关闭 MCP 等运行资源 |
+| `getSessionId()` | 获取当前会话 ID |
+| `saveCurrentSession()` | 立即保存会话 |
+| `resumeSession(id?)` | 恢复指定或最近会话 |
+| `clearConversation()` | 清空当前对话，不删除长期记忆 |
+| `getMessages()` | 获取当前消息数组；不要在请求执行期间修改 |
+| `getUsageStats()` | 获取 Token、缓存和分类用量 |
+| `compactConversation(force?)` | 主动执行语义压缩 |
+| `enterPlanMode()` / `approvePlan()` | 控制计划模式 |
+| `startGoal()` / `stopGoal()` | 控制目标模式 |
+| `startWorkflow()` / `stopWorkflow()` | 控制工作流模式 |
+
+## 记忆与会话工具
+
+SDK 还导出以下项目级函数：
+
+```ts
+import {
+  saveMemory,
+  searchMemories,
+  listMemories,
+  listSessions,
+  loadSession,
+  loadLatestSession,
+} from "@apolloyh/apollo-agent";
+```
+
+记忆保存在 `.apollo/memory/`，会话保存在 `.apollo/sessions/`。路径参数应使用对应项目的 `workspaceRoot`。
+
+## 集成原则
+
+- 每个对话一个 Engine。
+- 同一个 Engine 串行提交消息。
+- 每个用户或租户使用独立 `workspaceRoot` 和 `llmConfig`。
+- 应用退出、对话销毁或异常时始终调用 `close()`。
+- 服务端使用 `approvalProvider`，不要启用 `assumeYes`。
+- Node.js 之外的系统可在 SDK 外增加一层薄 HTTP/SSE 服务；Apollo SDK 本身不内置服务器。

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@apolloyh/apollo-agent",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Apollo — your personal agent. Answer first, act when needed. Claude Code–style Task subagents.",
+  "bin": {
+    "apollo": "./dist/index.js"
+  },
+  "main": "./dist/sdk.js",
+  "types": "./dist/sdk.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/sdk.d.ts",
+      "import": "./dist/sdk.js"
+    },
+    "./cli": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/skills/tech-research-skill",
+    "README.md",
+    "docs/sdk.md",
+    ".apollo/config.example.json",
+    ".env.example"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/index.js', 0o755)\"",
+    "dev": "tsx src/index.ts",
+    "prepack": "npm run build",
+    "start": "node dist/index.js",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "diff": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}