From 5e24f1f87c114ceb025c7e30ab4ef6c71be167de Mon Sep 17 00:00:00 2001 From: AlkaidSTART <2595006848@qq.com> Date: Thu, 6 Aug 2026 12:28:29 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20README=20=E5=B9=B6?= =?UTF-8?q?=E5=8A=A0=E5=85=A5=E4=BA=A7=E5=93=81=E5=9B=BE=E7=89=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 50 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 9176dd2..c31fb72 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # call-code +

+ call-code 产品标识 +

+ ![Node.js](https://img.shields.io/badge/Node.js-20%2B-339933?logo=nodedotjs&logoColor=white) ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white) ![pnpm](https://img.shields.io/badge/pnpm-F69220?logo=pnpm&logoColor=white) @@ -15,6 +19,8 @@ call-code 是一个本地运行的终端编程 Agent（CLI coding agent），基 - 结构化响应协议：模型输出统一为 `tool_call` 或 `final` 的 JSON action，循环解析并继续执行。 - 本地记忆：短期记忆按任务保存，长期记忆按主题沉淀，仅在进程内使用，不写入本地 JSON。 - 上下文预算：运行时基于 token 估算对历史消息做裁剪，减少超出模型上下文的风险。 +- 会话持久化：基于 Node 内置 `node:sqlite` 保存会话、条目、泳道、分支、记录、统计、事实和租约，默认写入 `.agent-sessions/sessions.db`。 +- 会话展示端：`packages/client` 提供 React + Vite 静态页面，可把会话数据导出为 JSON 后部署到 GitHub Pages。 ## 架构 @@ -64,22 +70,34 @@ packages/ policy/ # PLAN/BUILD 模式下的工具权限 web/ # GitHub Pages 客户端数据导出 client/ # TypeScript + React 会话历史界面，可部署到 GitHub Pages + session-sqlite/ # 基于 node:sqlite 的会话历史与运行状态存储 tests/ # 项目统一单元测试 vitest.config.ts # Vitest 测试配置 ``` +## 会话存储 + +会话历史由 `packages/session-sqlite` 持久化，默认数据库路径为 `.agent-sessions/sessions.db`。也可以通过 `SESSION_DB_PATH` 环境变量覆盖路径。数据层支持： + +- 会话：会话元数据、父子会话和当前工作目录。 +- 条目：用户、助手、工具和系统消息，支持泳道与分支。 +- 记录与统计：运行记录、token 消耗、成本等统计信息。 +- 事实与租约：供长任务复用的事实表，以及并发写入保护租约。 + ## 快速开始 1. 安装依赖（建议 Node.js 20+，并使用 pnpm）。 -2. 将 `.env.example` 复制为 `.env`，配置 `OPENAI_API_KEY`。 +2. 将 `.env.example` 复制为 `.env.local`（或 `.env`），配置 `OPENAI_API_KEY` 与 `OPENAI_MODEL`。 3. 启动 CLI，入口为 `source/app.tsx`。 ```bash -cp .env.example .env +cp .env.example .env.local pnpm install pnpm dev ``` +进入 CLI 后可以直接输入自然语言任务。CLI 默认按当前模式执行：`PLAN` 模式先生成计划，`BUILD` 模式直接参与文件读写和命令执行。计划生成后可用 Enter 确认执行，也可以继续补充修改意见。 + ## 环境变量 | 变量 | 说明 | @@ -88,6 +106,27 @@ pnpm dev | `OPENAI_API_BASE_URL` | 可选，自定义 OpenAI 兼容 base URL。 | | `OPENAI_MODEL` | 必填，模型名称，无默认值；未配置时 CLI 会提示。 | | `AGENT_DESKTOP_DIR` | 可选，覆盖桌面目录路径，便于测试或自定义工作环境。 | +| `SESSION_DB_PATH` | 可选，SQLite 会话库文件路径，默认 `.agent-sessions/sessions.db`。 | +| `CALL_CODE_WEB_DATA` | 可选，CLI 内 `/export` 的输出路径，默认 `packages/client/public/data.json`。 | + +## CLI 命令与快捷键 + +```text +/help 查看命令与快捷键 +/history 打开最近对话和相关页面选择 +/pages 打开相关页面选择 +/memory 查看 memory 概览 +/status 查看当前 CLI 状态 +/export 导出会话数据到 GitHub Pages 客户端 +/mode 查看当前模式和阶段 +/plan 切换到 PLAN 模式 +/build 切换到 BUILD 模式 +/clear 清空当前聊天窗口 +/home 返回首页并保留当前会话 +/exit 结束当前会话并返回首页 +``` + +快捷键：`Tab` 切换模式，`Ctrl+H` 打开历史选择，`Esc` 返回首页或退出选择，`Ctrl+C` 退出程序。 ## 常用命令 @@ -98,10 +137,16 @@ pnpm dev pnpm dev # 类型检查 -pnpm exec tsc -p tsconfig.json --noEmit +pnpm typecheck + +# 类型检查（session-sqlite） +pnpm exec tsc -p packages/session-sqlite/tsconfig.json --noEmit + +# 类型检查客户端 +pnpm typecheck:client -# 运行测试 -pnpm exec vitest run --reporter verbose +# 运行全部测试（推荐） +pnpm test # 构建 agent-core pnpm run build:agent-core