@gird/ccli 1.0.0

package/.env.example

@@ -0,0 +1,23 @@
+# CCLI 本地开发默认配置
+# 用法:复制本文件为 .env,填入 API Key 即可。
+#   cp .env.example .env
+# .env 已被 .gitignore 忽略,不会提交。启动时自动加载(真实环境变量优先)。
+
+# ───────────────────────────────────────────────
+# 后端二选一(不设 ANTHROPIC_API_KEY 时自动用 OpenAI 兼容后端)
+# ───────────────────────────────────────────────
+
+# 【方式 A】通义千问 Qwen(OpenAI 兼容,推荐用于本地开发)
+QWEN_API_KEY=sk-在这里填入你的千问key
+QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
+QWEN_MODEL=qwen-plus
+
+# 【方式 B】Anthropic 官方(若有 Claude key,取消注释即可,会优先生效)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=https://api.anthropic.com
+
+# 【方式 C】其他 OpenAI 兼容后端(DeepSeek / GLM / 自建)
+# OPENAI_API_KEY=...
+# OPENAI_BASE_URL=https://your-endpoint/v1
+# CCLI_MODEL=your-model
+# CCLI_PROVIDER=openai

package/CCLI.md

@@ -0,0 +1,15 @@
+# CCLI 项目说明（供 AI 助手阅读）
+
+这是一个用 TypeScript 实现的、复刻 Claude Code 的代理型终端 AI 编程助手。
+
+## 关键约定
+- 纯 ESM（`"type": "module"`），import 语句需带 `.js` 扩展名（指向编译产物）。
+- 运行时依赖仅 `@anthropic-ai/sdk`；其余为 Node 内置模块。
+- UI 不使用 Ink/React，全部用 `src/ui/theme.ts` 的 ANSI 工具手写。
+- 工具新增方式：实现 `src/tools/types.ts` 的 `Tool` 接口，在 `src/tools/index.ts` 注册。
+- 修改后用 `npm run build` 或 `npm run typecheck` 验证。
+
+## 开发命令
+- `npm run build` —— 编译到 `dist/`
+- `npm run typecheck` —— 仅类型检查
+- `npm run dev -- <args>` —— 用 tsx 直接运行源码

package/README.md

@@ -0,0 +1,187 @@
+# CCLI —— AI 软件工程师（Claude Code 复刻）
+
+一个**完整复刻 Claude Code** 的命令行 AI 编程助手。它不是一个简单的「问答机器人」，而是一个**代理型（Agentic）** 的终端工程师：你给出高层次目标，它自主规划步骤、读取文件、执行命令、修改代码并验证结果，直到任务完成。
+
+本项目对照 [`docs/主流AI-CLI工具对比说明.md`](./docs/主流AI-CLI工具对比说明.md) 中描述的 Claude CLI 架构实现，覆盖了文档列出的全部核心能力；并在 [`docs/差距/`](./docs/差距/) 目录中对照**真实 Claude Code** 逐项补齐了更多高级特性（TodoWrite、子代理、Hooks、会话恢复等）。
+
+## 特性
+
+对照对比文档中 Claude CLI 的技术规格逐项实现：
+
+| 文档中的能力 | 本项目实现 |
+|---|---|
+| **代理循环 Agentic Loop**（感知→推理→行动→验证） | `src/agent/loop.ts` —— 多轮工具调用状态机，最多 50 次迭代 |
+| **Anthropic Tool Use**（原生函数调用 + 动态注册） | `src/tools/` —— 7 个工具，`ToolRegistry` 支持动态注册 |
+| **HTTP/2 + SSE 流式传输** | `src/agent/client.ts` —— 基于官方 `@anthropic-ai/sdk` 流式接口 |
+| **本地能力**（child_process / fs / git） | `bash` / `read_file` / `write_file` / `edit_file` / `list_dir` 工具 |
+| **显式授权机制 + 权限白名单 + 二次确认** | `src/permissions/` —— 只读工具放行、写/命令需确认、高危命令告警、白名单持久化 |
+| **智能文件索引 + 分层上下文** | `src/context/project.ts` —— 目录树扫描、`CCLI.md` 注入、git 状态、系统提示缓存 |
+| **自定义终端 UI** | `src/ui/` —— ANSI 配色、Markdown 渲染、思考动画、确认框 |
+| **上下文管理** | `/clear` 清空、`/compact` 压缩、`/cost` 用量统计 |
+
+## 安装
+
+```bash
+npm install
+npm run build
+npm link        # 可选：全局安装 ccli 命令
+```
+
+## 配置
+
+支持两类后端协议,自动识别:
+
+**A. Anthropic（默认）**
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+export ANTHROPIC_BASE_URL=https://...   # 可选
+```
+
+**B. OpenAI 兼容（通义千问 Qwen / DeepSeek / GLM 等）**
+
+CLI 内置了 OpenAI Chat Completions 适配层,会在边界处把内部的 Anthropic 工具调用格式与 OpenAI 的 `tool_calls` 互转,因此完整的代理循环(工具调用、多轮)在这些后端上同样可用。
+
+```bash
+# 通义千问示例（DashScope 兼容端点）
+export QWEN_API_KEY=sk-...
+export QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
+export QWEN_MODEL=qwen-plus
+
+# 或通用 OpenAI 兼容
+export OPENAI_API_KEY=...
+export OPENAI_BASE_URL=https://your-endpoint/v1
+export CCLI_MODEL=your-model
+export CCLI_PROVIDER=openai   # 如需强制指定协议
+```
+
+未设置 `ANTHROPIC_API_KEY` 而检测到 `QWEN_API_KEY`/`OPENAI_API_KEY` 时,自动切换为 OpenAI 兼容协议。也可运行 `ccli config` 交互式保存到 `~/.ccli/config.json`。
+
+> 已实测:`qwen-plus` 上读文件、写文件、多轮工具调用均端到端可用。
+
+### 本地开发(推荐 .env)
+
+启动时会自动从当前目录(向上最多 5 层)加载 `.env`,**真实环境变量优先、不被覆盖**。
+所以本地开发不必每次 export,只需:
+
+```bash
+cp .env.example .env     # 模板已预填千问默认配置
+# 编辑 .env,把 QWEN_API_KEY 换成你的 key
+npm run dev -- "读一下 src/agent/loop.ts 并总结"   # tsx 直接跑源码
+# 或构建后:node dist/index.js
+```
+
+`.env` 已被 `.gitignore` 忽略,不会提交。
+
+## 使用
+
+> 完整使用指南(运行方式、输入快捷键、斜杠命令、工作流、常见问题)见 [`docs/使用指南.md`](./docs/使用指南.md)。
+
+```bash
+# 交互式会话（REPL）
+ccli
+
+# 直接给出目标
+ccli "给这个项目加一个命令行参数解析模块"
+
+# 一次性模式（适合脚本/管道）
+ccli -p "用一句话总结 src/agent/loop.ts 的作用"
+
+# 指定模型 / 自动批准
+ccli --model claude-sonnet-4-6
+ccli -y "运行测试并修复失败"
+```
+
+未全局安装时用 `npm run dev -- "你的目标"`（开发）或 `node dist/index.js`（构建后）。
+
+## 交互命令（Slash Commands）
+
+| 命令 | 说明 |
+|---|---|
+| `/help` | 显示所有命令 |
+| `/clear` | 清空对话历史 |
+| `/compact` | 压缩历史以节省上下文 |
+| `/model [id]` | 查看或切换模型 |
+| `/cost` | 本次会话 token 用量与估算成本（USD） |
+| `/init` | 分析项目并生成 CCLI.md |
+| `/commit` | 生成提交信息并 git 提交 |
+| `/resume` | 列出本目录的历史会话 |
+| `/auto` | 切换自动批准模式 |
+| `/permissions` | 查看权限白名单 |
+| `/status` | 会话状态 |
+| `/exit` | 退出 |
+
+输入框中：
+- `!<命令>` 直接执行 shell 命令
+- `#<文字>` 把一条规则写入 CCLI.md（长期记忆）
+- `@<路径>` 引用文件内容并入消息
+- `Ctrl+C` 中断当前生成；连按两次退出
+
+## 工具集
+
+| 工具 | 类型 | 说明 |
+|---|---|---|
+| `read_file` | 感知 | 读取文件（带行号，支持分段） |
+| `list_dir` | 感知 | 列目录 |
+| `grep` | 感知 | 正则搜索代码内容 |
+| `glob` | 感知 | 按文件名模式查找 |
+| `web_fetch` | 感知 | 抓取网页转文本（需授权） |
+| `write_file` | 行动 | 写入/创建文件（需授权，带 diff） |
+| `edit_file` | 行动 | 精确替换编辑（需授权，带行级 diff） |
+| `bash` | 行动 | 执行 shell 命令（需授权，高危告警） |
+| `todo_write` | 协调 | 维护多步任务清单并实时渲染进度 |
+| `task` | 协调 | 派生只读子代理做聚焦调研 |
+
+## 对齐真实 Claude Code 的高级特性
+
+在 [`docs/差距/`](./docs/差距/) 目录中,对照真实 Claude Code 逐项补齐(每项一份规格文档 + 代码实现):
+
+- **TodoWrite 任务追踪** — 模型把多步任务拆成清单,终端实时显示 `✔/▸/○` 进度
+- **WebFetch** — 抓取在线文档/网页
+- **`@文件` 引用** — 输入 `@src/x.ts` 自动并入文件内容
+- **会话持久化** — `ccli -c` 续聊上次、`ccli -r [id]` 列出/恢复历史会话
+- **自定义斜杠命令** — `.ccli/commands/<名>.md` 即定义 `/<名>`,支持 `$ARGUMENTS`
+- **行级 diff 渲染** — 编辑后展示真正的 +/- diff(LCS 算法)
+- **子代理 / Task 工具** — 派生独立上下文的只读子代理做调研
+- **Hooks 生命周期钩子** — `.ccli/settings.json` 配置 `PreToolUse`(可拦截)/`PostToolUse`
+- **流式 Markdown 实时渲染** — 流式正文按完整行实时套用 markdown(标题/列表/代码块/行内样式)
+- **真实定价 `/cost`** — 按模型单价估算美元成本
+- **`#` 写记忆** — `#<文字>` 追加规则到 CCLI.md
+- **`/init`** — 让 agent 分析项目生成 CCLI.md
+- **`/commit`** — 让 agent 总结改动并 git 提交
+
+尚未实施的项(MCP、图片输入、WebSearch、Vim 模式等)及理由见 [`docs/差距/09-未实施.md`](./docs/差距/09-未实施.md)。
+
+## 架构
+
+> 完整的架构说明(设计理念、分层图、代理循环数据流、各模块职责、扩展指南)见 [`docs/架构设计.md`](./docs/架构设计.md)。
+
+```
+src/
+├── index.ts            入口：参数解析、API Key 引导、会话恢复
+├── agent/
+│   ├── loop.ts         代理循环（核心状态机，含 Hooks 集成）
+│   ├── client.ts       Anthropic API 流式封装
+│   ├── factory.ts      Agent 装配（工具 + Todo + Hooks + 子代理）
+│   └── prompt.ts       系统提示词
+├── tools/              工具系统：filesystem / search / bash / todo / web / task
+├── permissions/        权限/授权机制
+├── context/            项目上下文扫描与索引
+├── hooks/              生命周期钩子（Pre/PostToolUse）
+├── session/            会话持久化（continue/resume）
+├── commands/           斜杠命令 + 自定义命令加载
+├── config/             配置管理
+├── cli/
+│   ├── session.ts      交互式 REPL
+│   ├── headless.ts     一次性模式
+│   └── mentions.ts     @文件引用展开
+└── ui/                 终端 UI（配色 / Markdown / diff / 动画）
+
+docs/                   文档
+├── 主流AI-CLI工具对比说明.md
+└── 差距/               与真实 Claude Code 的差距分析与实施记录
+```
+
+## 许可
+
+MIT

package/dist/agent/client-openai.js

@@ -0,0 +1,166 @@
+/**
+ * OpenAI 兼容客户端 —— 对接 OpenAI Chat Completions 协议的后端,
+ * 例如通义千问(DashScope compatible-mode)、DeepSeek、GLM 等。
+ *
+ * 它在边界处把代理循环内部使用的 Anthropic 消息格式(含 tool_use / tool_result 块)
+ * 与 OpenAI 的 messages / tool_calls 格式互相转换,从而让上层循环逻辑保持不变。
+ */
+import OpenAI from 'openai';
+export class OpenAICompatClient {
+    client;
+    model;
+    maxTokens;
+    temperature;
+    constructor(opts) {
+        this.client = new OpenAI({ apiKey: opts.apiKey, baseURL: opts.baseURL });
+        this.model = opts.model;
+        this.maxTokens = opts.maxTokens;
+        this.temperature = opts.temperature;
+    }
+    setModel(m) {
+        this.model = m;
+    }
+    getModel() {
+        return this.model;
+    }
+    async stream(system, messages, tools, callbacks, signal) {
+        const oaMessages = this.toOpenAIMessages(system, messages);
+        const oaTools = tools.map((t) => ({
+            type: 'function',
+            function: {
+                name: t.name,
+                description: t.description,
+                parameters: t.input_schema ?? { type: 'object', properties: {} },
+            },
+        }));
+        const stream = await this.client.chat.completions.create({
+            model: this.model,
+            max_tokens: this.maxTokens,
+            temperature: this.temperature,
+            messages: oaMessages,
+            tools: oaTools.length ? oaTools : undefined,
+            tool_choice: oaTools.length ? 'auto' : undefined,
+            stream: true,
+            stream_options: { include_usage: true },
+        }, { signal });
+        let text = '';
+        let finishReason = null;
+        const usage = { input: 0, output: 0 };
+        // 按 index 累积 tool_calls
+        const toolAcc = new Map();
+        for await (const chunk of stream) {
+            const choice = chunk.choices?.[0];
+            if (choice) {
+                const delta = choice.delta;
+                if (delta?.content) {
+                    text += delta.content;
+                    callbacks.onText?.(delta.content);
+                }
+                if (delta?.tool_calls) {
+                    for (const tc of delta.tool_calls) {
+                        const idx = tc.index ?? 0;
+                        const cur = toolAcc.get(idx) ?? { id: '', name: '', args: '' };
+                        if (tc.id)
+                            cur.id = tc.id;
+                        if (tc.function?.name)
+                            cur.name = tc.function.name;
+                        if (tc.function?.arguments)
+                            cur.args += tc.function.arguments;
+                        toolAcc.set(idx, cur);
+                        if (tc.function?.name)
+                            callbacks.onToolUseStart?.(tc.function.name, cur.id);
+                    }
+                }
+                if (choice.finish_reason)
+                    finishReason = choice.finish_reason;
+            }
+            if (chunk.usage) {
+                usage.input = chunk.usage.prompt_tokens ?? 0;
+                usage.output = chunk.usage.completion_tokens ?? 0;
+            }
+        }
+        // 组装 Anthropic 内部格式的 content 块
+        const content = [];
+        if (text)
+            content.push({ type: 'text', text });
+        let genId = 0;
+        for (const [, tc] of [...toolAcc.entries()].sort((a, b) => a[0] - b[0])) {
+            let input = {};
+            try {
+                input = tc.args ? JSON.parse(tc.args) : {};
+            }
+            catch {
+                input = {};
+            }
+            content.push({
+                type: 'tool_use',
+                id: tc.id || `call_${Date.now()}_${genId++}`,
+                name: tc.name,
+                input,
+            });
+        }
+        const stopReason = finishReason === 'tool_calls'
+            ? 'tool_use'
+            : finishReason === 'length'
+                ? 'max_tokens'
+                : 'end_turn';
+        return { content, stopReason, usage };
+    }
+    /** Anthropic 内部消息 → OpenAI messages。 */
+    toOpenAIMessages(system, messages) {
+        const out = [
+            { role: 'system', content: system },
+        ];
+        for (const m of messages) {
+            if (typeof m.content === 'string') {
+                out.push({ role: m.role, content: m.content });
+                continue;
+            }
+            const blocks = m.content;
+            if (m.role === 'assistant') {
+                let textContent = '';
+                const toolCalls = [];
+                for (const b of blocks) {
+                    if (b.type === 'text')
+                        textContent += b.text;
+                    else if (b.type === 'tool_use') {
+                        toolCalls.push({
+                            id: b.id,
+                            type: 'function',
+                            function: {
+                                name: b.name,
+                                arguments: JSON.stringify(b.input ?? {}),
+                            },
+                        });
+                    }
+                }
+                const msg = { role: 'assistant' };
+                msg.content = textContent || null;
+                if (toolCalls.length)
+                    msg.tool_calls = toolCalls;
+                out.push(msg);
+                continue;
+            }
+            // user 消息:可能含 tool_result 与 text
+            const userTexts = [];
+            for (const b of blocks) {
+                if (b.type === 'tool_result') {
+                    out.push({
+                        role: 'tool',
+                        tool_call_id: b.tool_use_id,
+                        content: typeof b.content === 'string'
+                            ? b.content
+                            : JSON.stringify(b.content),
+                    });
+                }
+                else if (b.type === 'text') {
+                    userTexts.push(b.text);
+                }
+            }
+            if (userTexts.length) {
+                out.push({ role: 'user', content: userTexts.join('\n') });
+            }
+        }
+        return out;
+    }
+}

package/dist/agent/client.js

@@ -0,0 +1,63 @@
+/**
+ * Anthropic Messages API 客户端封装 —— HTTP/2 + SSE 流式传输。
+ */
+import Anthropic from '@anthropic-ai/sdk';
+export class AnthropicClient {
+    client;
+    model;
+    maxTokens;
+    temperature;
+    constructor(opts) {
+        this.client = new Anthropic({
+            apiKey: opts.apiKey,
+            baseURL: opts.baseURL,
+        });
+        this.model = opts.model;
+        this.maxTokens = opts.maxTokens;
+        this.temperature = opts.temperature;
+    }
+    setModel(m) {
+        this.model = m;
+    }
+    getModel() {
+        return this.model;
+    }
+    /**
+     * 发起一次带流式输出的对话请求。
+     * 返回完整的 assistant 回合（含文本与 tool_use 块）。
+     */
+    async stream(system, messages, tools, callbacks, signal) {
+        const stream = this.client.messages.stream({
+            model: this.model,
+            max_tokens: this.maxTokens,
+            temperature: this.temperature,
+            system: [
+                {
+                    type: 'text',
+                    text: system,
+                    // 系统提示缓存（对应「分层上下文压缩」中的缓存策略）
+                    cache_control: { type: 'ephemeral' },
+                },
+            ],
+            messages,
+            tools: tools.length ? tools : undefined,
+        }, { signal });
+        stream.on('text', (delta) => callbacks.onText?.(delta));
+        stream.on('contentBlock', (block) => {
+            if (block.type === 'tool_use') {
+                callbacks.onToolUseStart?.(block.name, block.id);
+            }
+        });
+        // thinking（若启用扩展思考）
+        stream.on('thinking', (delta) => callbacks.onThinking?.(delta));
+        const final = await stream.finalMessage();
+        return {
+            content: final.content,
+            stopReason: final.stop_reason,
+            usage: {
+                input: final.usage.input_tokens,
+                output: final.usage.output_tokens,
+            },
+        };
+    }
+}

package/dist/agent/factory.js

@@ -0,0 +1,39 @@
+import { Agent } from './loop.js';
+import { buildSystemPrompt } from './prompt.js';
+import { createDefaultRegistry, createReadOnlyRegistry, } from '../tools/index.js';
+import { TodoStore } from '../tools/todo.js';
+import { createTaskTool, SUBAGENT_SYSTEM, } from '../tools/task.js';
+import { HookRunner } from '../hooks/hooks.js';
+import { gatherContext } from '../context/project.js';
+export function buildAgent(opts) {
+    const { client, cwd, permissions } = opts;
+    const todos = new TodoStore();
+    const hooks = new HookRunner(cwd);
+    const registry = createDefaultRegistry();
+    // 子代理运行器:用只读工具集跑一个独立 Agent,返回最终文本。
+    const runner = async (description, prompt, subCwd) => {
+        const subRegistry = createReadOnlyRegistry();
+        const subAgent = new Agent(client, subRegistry, permissions, SUBAGENT_SYSTEM, { cwd: subCwd }, hooks);
+        let text = '';
+        let isError = false;
+        try {
+            await subAgent.run(prompt, {
+                onAssistantText: (d) => {
+                    text += d;
+                },
+                onTurnStart: () => { },
+                onTurnEnd: () => { },
+            });
+        }
+        catch (e) {
+            isError = true;
+            text = `子代理出错:${e?.message ?? e}`;
+        }
+        return { text: text.trim(), isError };
+    };
+    registry.register(createTaskTool(runner));
+    const ctx = gatherContext(cwd);
+    const system = buildSystemPrompt(ctx);
+    const agent = new Agent(client, registry, permissions, system, { cwd, todos }, hooks);
+    return { agent, todos, hooks, client };
+}

package/dist/agent/loop.js

@@ -0,0 +1,163 @@
+import { toAnthropicTool } from '../tools/index.js';
+const MAX_ITERATIONS = 50;
+export class Agent {
+    client;
+    registry;
+    permissions;
+    system;
+    toolCtx;
+    hooks;
+    history = [];
+    totalUsage = { input: 0, output: 0 };
+    constructor(client, registry, permissions, system, toolCtx, hooks) {
+        this.client = client;
+        this.registry = registry;
+        this.permissions = permissions;
+        this.system = system;
+        this.toolCtx = toolCtx;
+        this.hooks = hooks;
+    }
+    setSystem(s) {
+        this.system = s;
+    }
+    /** 处理一条用户输入，驱动完整的代理循环直到回合结束。 */
+    async run(userInput, events, signal) {
+        this.history.push({ role: 'user', content: userInput });
+        await this.loop(events, signal);
+    }
+    /** 注入工具结果后继续循环（用于外部恢复，一般内部调用）。 */
+    async loop(events, signal) {
+        const tools = this.registry.list().map(toAnthropicTool);
+        for (let i = 0; i < MAX_ITERATIONS; i++) {
+            if (signal?.aborted)
+                return;
+            events.onTurnStart?.();
+            let turn;
+            try {
+                turn = await this.client.stream(this.system, this.history, tools, {
+                    onText: (d) => events.onAssistantText?.(d),
+                    onThinking: (d) => events.onThinking?.(d),
+                }, signal);
+            }
+            catch (e) {
+                events.onTurnEnd?.();
+                if (signal?.aborted)
+                    return;
+                throw e;
+            }
+            events.onTurnEnd?.();
+            this.totalUsage.input += turn.usage.input;
+            this.totalUsage.output += turn.usage.output;
+            events.onUsage?.(turn.usage);
+            // 记录 assistant 回合
+            this.history.push({ role: 'assistant', content: turn.content });
+            // 收集 tool_use 块
+            const toolUses = turn.content.filter((b) => b.type === 'tool_use');
+            if (toolUses.length === 0) {
+                // 没有工具调用 —— 回合结束
+                return;
+            }
+            // 依次执行工具，收集 tool_result
+            const toolResults = [];
+            for (const tu of toolUses) {
+                if (signal?.aborted) {
+                    toolResults.push({
+                        type: 'tool_result',
+                        tool_use_id: tu.id,
+                        content: '用户中断了操作。',
+                        is_error: true,
+                    });
+                    continue;
+                }
+                const result = await this.executeTool(tu, events);
+                toolResults.push(result);
+            }
+            // 把工具结果作为新的 user 消息回传
+            this.history.push({ role: 'user', content: toolResults });
+            // 继续循环
+        }
+        // 达到迭代上限
+        this.history.push({
+            role: 'user',
+            content: '已达到工具调用上限，请总结当前进展。',
+        });
+    }
+    async executeTool(tu, events) {
+        const tool = this.registry.get(tu.name);
+        if (!tool) {
+            return {
+                type: 'tool_result',
+                tool_use_id: tu.id,
+                content: `未知工具：${tu.name}`,
+                is_error: true,
+            };
+        }
+        const preview = tool.preview ? tool.preview(tu.input, this.toolCtx) : tu.name;
+        events.onToolStart?.(tu.name, tu.input, preview);
+        // 权限检查
+        if (tool.permission) {
+            const req = tool.permission(tu.input, this.toolCtx);
+            if (req) {
+                const decision = await this.permissions.check(req);
+                if (decision === 'deny') {
+                    events.onToolDenied?.(tu.name, '用户拒绝了该操作');
+                    return {
+                        type: 'tool_result',
+                        tool_use_id: tu.id,
+                        content: '用户拒绝执行此操作。请不要重试相同操作，可以询问用户希望如何继续。',
+                        is_error: true,
+                    };
+                }
+            }
+        }
+        // PreToolUse 钩子:可阻止工具
+        if (this.hooks) {
+            const pre = this.hooks.runPre(tu.name, tu.input);
+            if (pre.blocked) {
+                events.onToolDenied?.(tu.name, `钩子拦截：${pre.reason ?? ''}`);
+                return {
+                    type: 'tool_result',
+                    tool_use_id: tu.id,
+                    content: `操作被 PreToolUse 钩子阻止：${pre.reason ?? '(无理由)'}`,
+                    is_error: true,
+                };
+            }
+        }
+        // 执行
+        try {
+            const res = await tool.run(tu.input, this.toolCtx);
+            this.hooks?.runPost(tu.name, tu.input, res.content);
+            events.onToolResult?.(tu.name, res.display ?? res.content.slice(0, 200), res.isError ?? false);
+            return {
+                type: 'tool_result',
+                tool_use_id: tu.id,
+                content: res.content,
+                is_error: res.isError ?? false,
+            };
+        }
+        catch (e) {
+            events.onToolResult?.(tu.name, `执行异常：${e.message}`, true);
+            return {
+                type: 'tool_result',
+                tool_use_id: tu.id,
+                content: `工具执行异常：${e.message}`,
+                is_error: true,
+            };
+        }
+    }
+    /** 清空对话历史（/clear）。 */
+    clear() {
+        this.history = [];
+        this.totalUsage = { input: 0, output: 0 };
+    }
+    /** 压缩历史（/compact）—— 简化实现：保留最近若干轮 + 摘要占位。 */
+    compactSummary(summary) {
+        this.history = [
+            { role: 'user', content: `[此前对话的摘要]\n${summary}` },
+            {
+                role: 'assistant',
+                content: '好的，我已了解此前的上下文，请继续。',
+            },
+        ];
+    }
+}

package/dist/agent/pricing.js

@@ -0,0 +1,28 @@
+const PRICES = [
+    { match: /opus/i, price: { input: 15, output: 75 } },
+    { match: /sonnet/i, price: { input: 3, output: 15 } },
+    { match: /haiku/i, price: { input: 0.8, output: 4 } },
+    // OpenAI 兼容后端(近似值,仅供参考)
+    { match: /qwen-max/i, price: { input: 1.6, output: 6.4 } },
+    { match: /qwen-plus/i, price: { input: 0.4, output: 1.2 } },
+    { match: /qwen-turbo|qwen-flash/i, price: { input: 0.05, output: 0.2 } },
+    { match: /qwen/i, price: { input: 0.4, output: 1.2 } },
+    { match: /deepseek/i, price: { input: 0.27, output: 1.1 } },
+    { match: /glm/i, price: { input: 0.5, output: 1.5 } },
+];
+const FALLBACK = { input: 3, output: 15 };
+export function priceFor(model) {
+    return PRICES.find((p) => p.match.test(model))?.price ?? FALLBACK;
+}
+/** 计算给定用量的美元成本。 */
+export function estimateCost(model, usage) {
+    const p = priceFor(model);
+    const input = (usage.input / 1_000_000) * p.input;
+    const output = (usage.output / 1_000_000) * p.output;
+    return { input, output, total: input + output };
+}
+export function formatUsd(n) {
+    if (n < 0.01)
+        return `$${n.toFixed(4)}`;
+    return `$${n.toFixed(4)}`;
+}