@gird/ccli 2.0.0 → 2.0.1

package/README.md

@@ -4,26 +4,17 @@
 [![license](https://img.shields.io/npm/l/@gird/ccli.svg)](./LICENSE)
 [![node](https://img.shields.io/node/v/@gird/ccli.svg)](https://nodejs.org)
 
-**CCLI** 是一个运行在终端里的**代理型（Agentic）AI 编程助手**。你给出高层目标，它自主地阅读代码、检索、执行命令、修改文件并验证结果，直到任务完成——而不只是回答一个问题。
+**CCLI** —— 一个**从零开始、一步一步**实现的代理型（Agentic）终端 AI 编程助手。
 
-它支持 **Anthropic Claude** 与 **OpenAI 兼容**后端（通义千问 Qwen、DeepSeek、GLM 等），完整的工具调用与多轮代理循环在两类后端上均可用。
+> ⚠️ **重建中（work in progress）**：本项目正在从零逐步重写，力求每一步都简单、可读、可运行。
+> 当前进度见下方「实现进度」。每一步都配有说明文档，放在 [`docs/steps/`](docs/steps/)。
 
-```bash
-npm install -g @gird/ccli
-ccli            # 首次运行会引导你配置模型与密钥
-```
-
----
+## 为什么重写
 
-## 特性
-
-- **代理循环** —— 感知（读文件 / 跑命令 / 检索）→ 推理 → 行动 → 验证，自动多轮直到目标完成。
-- **多后端** —— 一套接口适配 Anthropic Messages API 与 OpenAI Chat Completions（千问 / DeepSeek / GLM…），自动识别。
-- **丰富工具集** —— 读写与精确编辑文件、grep / glob 检索、shell 执行、网页抓取、子代理调研、任务清单。
-- **安全可控** —— 只读操作放行；写文件 / 执行命令前显式授权；高危命令（`rm -rf`、`git push`…）告警；支持钩子拦截。
-- **上下文工程** —— 自动索引项目结构、注入 `CCLI.md` 项目记忆、`/compact` 压缩、`/cost` 成本统计。
-- **顺手的交互** —— 流式 Markdown 渲染、`@文件` 引用、`!` 直通 shell、`#` 写长期记忆、会话恢复、自定义斜杠命令。
-- **零重型依赖** —— 纯 TypeScript 实现，运行时仅依赖官方 SDK。
+上一版实现一次性堆了太多功能，代码复杂到难以通读。现在推倒重来，遵循一个原则：
+**从最小可运行的骨架开始，每次只加一个能独立讲清楚的功能，并为它写一份文档**
+（这一步做什么、怎么做的、遇到什么问题、下一步是什么）。目标是过程可追、代码好懂，
+最终长成一个可发布的工具。
 
 ## 安装
 
@@ -33,18 +24,17 @@ npm install -g @gird/ccli
 
 要求 Node.js ≥ 18。
 
-## 快速开始
+## 用法
 
 ```bash
-ccli                          # 进入交互式会话，首次运行引导配置
-ccli "为这个项目添加单元测试"    # 直接给出目标
-ccli -p "总结 src 的结构"       # 一次性模式（适合脚本 / 管道）
+ccli              # 进入交互式会话
+ccli --version    # 打印版本号
+ccli --help       # 打印帮助
 ```
 
 ## 配置
 
-CCLI 自动识别后端协议。密钥来源优先级：**环境变量 > 项目 `.env` > 全局 `~/.ccli/config.json`**。
-首次运行 `ccli` 会弹出引导菜单帮你完成配置，也可手动设置：
+密钥来源优先级：**环境变量 > 项目 `.env` > 全局 `~/.ccli/config.json`**。
 
 **Anthropic Claude**
 
@@ -58,47 +48,18 @@ export ANTHROPIC_API_KEY=sk-ant-...
 export QWEN_API_KEY=sk-...
 export QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
 export QWEN_MODEL=qwen-plus
-# 或通用：OPENAI_API_KEY / OPENAI_BASE_URL / CCLI_MODEL / CCLI_PROVIDER=openai
+# 或通用：OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL
 ```
 
-## 命令行用法
-
-```bash
-ccli [目标]            进入交互式会话（可附带初始目标）
-ccli -p, --print <文本>   一次性模式，输出后退出
-ccli -m, --model <id>     指定模型，如 -m qwen-max
-ccli -c, --continue       恢复本目录最近一次会话
-ccli -r, --resume [id]    列出 / 恢复历史会话
-ccli -y, --yes            自动批准所有工具（慎用）
-ccli config               配置密钥
-ccli -h, --help           查看帮助
-```
-
-## 交互
-
-进入会话后，输入框支持：
-
-| 输入 | 作用 |
-| --- | --- |
-| 直接输入 | 与 AI 对话，触发代理循环 |
-| `@<路径>` | 将文件 / 目录内容并入消息 |
-| `!<命令>` | 直接执行 shell 命令 |
-| `#<文字>` | 将一条规则写入 `CCLI.md`（长期记忆） |
-
-常用斜杠命令：`/help` `/model` `/cost` `/init` `/commit` `/resume` `/compact` `/clear` `/auto` `/exit`。
-在 `.ccli/commands/<名>.md` 放置提示词模板即可定义自定义命令 `/<名>`。
-
-## 工具
+## 实现进度
 
-| 工具 | 类型 | 说明 |
+| 步骤 | 内容 | 文档 |
 | --- | --- | --- |
-| `read_file` / `list_dir` | 感知 | 读取文件（带行号）、列目录 |
-| `grep` / `glob` | 感知 | 正则检索内容、按模式匹配文件 |
-| `web_fetch` | 感知 | 抓取网页并转为文本 |
-| `write_file` / `edit_file` | 行动 | 创建 / 覆盖、精确替换编辑（带行级 diff） |
-| `bash` | 行动 | 执行 shell 命令（受权限约束，高危告警） |
-| `todo_write` | 协调 | 维护多步任务清单并实时显示进度 |
-| `task` | 协调 | 派生只读子代理执行聚焦调研 |
+| 01 | 最小可执行入口 | [docs/steps/01-入口.md](docs/steps/01-入口.md) |
+| 02 | 命令行参数解析（`--version` / `--help`） | [docs/steps/02-参数解析.md](docs/steps/02-参数解析.md) |
+| 03 | 交互式会话循环（REPL） | [docs/steps/03-交互循环.md](docs/steps/03-交互循环.md) |
+| 04 | 配置与密钥读取 | [docs/steps/04-配置读取.md](docs/steps/04-配置读取.md) |
+| … | 接入 AI、工具调用、代理循环… | 进行中 |
 
 ## 本地开发
 
@@ -107,7 +68,7 @@ git clone https://github.com/GridGit/ai-cli.git
 cd ai-cli
 npm install
 cp .env.example .env          # 填入密钥
-npm run dev -- "你的目标"      # 用 tsx 直接运行源码
+npm run dev                   # 用 tsx 直接运行源码（免编译）
 npm run build                 # 编译到 dist/
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gird/ccli",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "CCLI —— 一步一步从零实现的代理型（Agentic）终端 AI 编程助手",
   "type": "module",
   "bin": {