Skip to content

docs: 完善 README 并加入产品图片 #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AlkaidSTART merged 1 commit into from
Aug 6, 2026
Merged

docs: 完善 README 并加入产品图片 #8

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 50 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# call-code

<p align="center">
<img src="packages/client/assets/call-code.png" alt="call-code 产品标识" width="240" />
</p>

![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)
Expand All @@ -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。

## 架构

Expand Down Expand Up @@ -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 确认执行，也可以继续补充修改意见。

## 环境变量

| 变量 | 说明 |
Expand All @@ -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` 退出程序。

## 常用命令

Expand All @@ -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
Expand Down
Loading