@gird/ccli 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +78 -144
  3. package/package.json +1 -1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 gird
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,187 +1,121 @@
1
- # CCLI —— AI 软件工程师（Claude Code 复刻）
1
+ # CCLI
2
2
 
3
- 一个**完整复刻 Claude Code** 的命令行 AI 编程助手。它不是一个简单的「问答机器人」，而是一个**代理型（Agentic）** 的终端工程师：你给出高层次目标，它自主规划步骤、读取文件、执行命令、修改代码并验证结果，直到任务完成。
3
+ [![npm version](https://img.shields.io/npm/v/@gird/ccli.svg)](https://www.npmjs.com/package/@gird/ccli)
4
+ [![license](https://img.shields.io/npm/l/@gird/ccli.svg)](./LICENSE)
5
+ [![node](https://img.shields.io/node/v/@gird/ccli.svg)](https://nodejs.org)
4
6
 
5
- 本项目对照 [`docs/主流AI-CLI工具对比说明.md`](./docs/主流AI-CLI工具对比说明.md) 中描述的 Claude CLI 架构实现，覆盖了文档列出的全部核心能力；并在 [`docs/差距/`](./docs/差距/) 目录中对照**真实 Claude Code** 逐项补齐了更多高级特性（TodoWrite、子代理、Hooks、会话恢复等）。
7
+ **CCLI** 是一个运行在终端里的**代理型（Agentic）AI 编程助手**。你给出高层目标，它自主地阅读代码、检索、执行命令、修改文件并验证结果，直到任务完成——而不只是回答一个问题。
6
8
 
7
- ## 特性
9
+ 它支持 **Anthropic Claude** 与 **OpenAI 兼容**后端（通义千问 Qwen、DeepSeek、GLM 等），完整的工具调用与多轮代理循环在两类后端上均可用。
10
+
11
+ ```bash
12
+ npm install -g @gird/ccli
13
+ ccli # 首次运行会引导你配置模型与密钥
14
+ ```
15
+
16
+ ---
8
17
 
9
- 对照对比文档中 Claude CLI 的技术规格逐项实现：
18
+ ## 特性
10
19
 
11
- | 文档中的能力 | 本项目实现 |
12
- |---|---|
13
- | **代理循环 Agentic Loop**（感知→推理→行动→验证） | `src/agent/loop.ts` —— 多轮工具调用状态机，最多 50 次迭代 |
14
- | **Anthropic Tool Use**（原生函数调用 + 动态注册） | `src/tools/` —— 7 个工具，`ToolRegistry` 支持动态注册 |
15
- | **HTTP/2 + SSE 流式传输** | `src/agent/client.ts` —— 基于官方 `@anthropic-ai/sdk` 流式接口 |
16
- | **本地能力**（child_process / fs / git） | `bash` / `read_file` / `write_file` / `edit_file` / `list_dir` 工具 |
17
- | **显式授权机制 + 权限白名单 + 二次确认** | `src/permissions/` —— 只读工具放行、写/命令需确认、高危命令告警、白名单持久化 |
18
- | **智能文件索引 + 分层上下文** | `src/context/project.ts` —— 目录树扫描、`CCLI.md` 注入、git 状态、系统提示缓存 |
19
- | **自定义终端 UI** | `src/ui/` —— ANSI 配色、Markdown 渲染、思考动画、确认框 |
20
- | **上下文管理** | `/clear` 清空、`/compact` 压缩、`/cost` 用量统计 |
20
+ - **代理循环** —— 感知（读文件 / 跑命令 / 检索）→ 推理 → 行动 → 验证，自动多轮直到目标完成。
21
+ - **多后端** —— 一套接口适配 Anthropic Messages API 与 OpenAI Chat Completions（千问 / DeepSeek / GLM…），自动识别。
22
+ - **丰富工具集** —— 读写与精确编辑文件、grep / glob 检索、shell 执行、网页抓取、子代理调研、任务清单。
23
+ - **安全可控** —— 只读操作放行；写文件 / 执行命令前显式授权；高危命令（`rm -rf`、`git push`…）告警；支持钩子拦截。
24
+ - **上下文工程** —— 自动索引项目结构、注入 `CCLI.md` 项目记忆、`/compact` 压缩、`/cost` 成本统计。
25
+ - **顺手的交互** —— 流式 Markdown 渲染、`@文件` 引用、`!` 直通 shell、`#` 写长期记忆、会话恢复、自定义斜杠命令。
26
+ - **零重型依赖** —— 纯 TypeScript 实现，运行时仅依赖官方 SDK。
21
27
 
22
28
  ## 安装
23
29
 
24
30
  ```bash
25
- npm install
26
- npm run build
27
- npm link # 可选：全局安装 ccli 命令
31
+ npm install -g @gird/ccli
32
+ ```
33
+
34
+ 要求 Node.js ≥ 18。
35
+
36
+ ## 快速开始
37
+
38
+ ```bash
39
+ ccli # 进入交互式会话，首次运行引导配置
40
+ ccli "为这个项目添加单元测试" # 直接给出目标
41
+ ccli -p "总结 src 的结构" # 一次性模式（适合脚本 / 管道）
28
42
  ```
29
43
 
30
44
  ## 配置
31
45
 
32
- 支持两类后端协议,自动识别:
46
+ CCLI 自动识别后端协议。密钥来源优先级：**环境变量 > 项目 `.env` > 全局 `~/.ccli/config.json`**。
47
+ 首次运行 `ccli` 会弹出引导菜单帮你完成配置，也可手动设置：
33
48
 
34
- **A. Anthropic（默认）**
49
+ **Anthropic Claude**
35
50
 
36
51
  ```bash
37
52
  export ANTHROPIC_API_KEY=sk-ant-...
38
- export ANTHROPIC_BASE_URL=https://... # 可选
39
53
  ```
40
54
 
41
- **B. OpenAI 兼容（通义千问 Qwen / DeepSeek / GLM 等）**
42
-
43
- CLI 内置了 OpenAI Chat Completions 适配层,会在边界处把内部的 Anthropic 工具调用格式与 OpenAI 的 `tool_calls` 互转,因此完整的代理循环(工具调用、多轮)在这些后端上同样可用。
55
+ **OpenAI 兼容（通义千问 / DeepSeek / GLM…）**
44
56
 
45
57
  ```bash
46
- # 通义千问示例（DashScope 兼容端点）
47
58
  export QWEN_API_KEY=sk-...
48
59
  export QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
49
60
  export QWEN_MODEL=qwen-plus
50
-
51
- # 或通用 OpenAI 兼容
52
- export OPENAI_API_KEY=...
53
- export OPENAI_BASE_URL=https://your-endpoint/v1
54
- export CCLI_MODEL=your-model
55
- export CCLI_PROVIDER=openai # 如需强制指定协议
61
+ # 或通用：OPENAI_API_KEY / OPENAI_BASE_URL / CCLI_MODEL / CCLI_PROVIDER=openai
56
62
  ```
57
63
 
58
- 未设置 `ANTHROPIC_API_KEY` 而检测到 `QWEN_API_KEY`/`OPENAI_API_KEY` 时,自动切换为 OpenAI 兼容协议。也可运行 `ccli config` 交互式保存到 `~/.ccli/config.json`。
59
-
60
- > 已实测:`qwen-plus` 上读文件、写文件、多轮工具调用均端到端可用。
61
-
62
- ### 本地开发(推荐 .env)
63
-
64
- 启动时会自动从当前目录(向上最多 5 层)加载 `.env`,**真实环境变量优先、不被覆盖**。
65
- 所以本地开发不必每次 export,只需:
64
+ ## 命令行用法
66
65
 
67
66
  ```bash
68
- cp .env.example .env # 模板已预填千问默认配置
69
- # 编辑 .env,把 QWEN_API_KEY 换成你的 key
70
- npm run dev -- "读一下 src/agent/loop.ts 并总结" # tsx 直接跑源码
71
- # 或构建后:node dist/index.js
67
+ ccli [目标] 进入交互式会话（可附带初始目标）
68
+ ccli -p, --print <文本> 一次性模式，输出后退出
69
+ ccli -m, --model <id> 指定模型，如 -m qwen-max
70
+ ccli -c, --continue 恢复本目录最近一次会话
71
+ ccli -r, --resume [id] 列出 / 恢复历史会话
72
+ ccli -y, --yes 自动批准所有工具（慎用）
73
+ ccli config 配置密钥
74
+ ccli -h, --help 查看帮助
72
75
  ```
73
76
 
74
- `.env` 已被 `.gitignore` 忽略,不会提交。
77
+ ## 交互
75
78
 
76
- ## 使用
79
+ 进入会话后，输入框支持：
77
80
 
78
- > 完整使用指南(运行方式、输入快捷键、斜杠命令、工作流、常见问题)见 [`docs/使用指南.md`](./docs/使用指南.md)。
81
+ | 输入 | 作用 |
82
+ | --- | --- |
83
+ | 直接输入 | 与 AI 对话，触发代理循环 |
84
+ | `@<路径>` | 将文件 / 目录内容并入消息 |
85
+ | `!<命令>` | 直接执行 shell 命令 |
86
+ | `#<文字>` | 将一条规则写入 `CCLI.md`（长期记忆） |
79
87
 
80
- ```bash
81
- # 交互式会话（REPL）
82
- ccli
88
+ 常用斜杠命令：`/help` `/model` `/cost` `/init` `/commit` `/resume` `/compact` `/clear` `/auto` `/exit`。
89
+ 在 `.ccli/commands/<名>.md` 放置提示词模板即可定义自定义命令 `/<名>`。
83
90
 
84
- # 直接给出目标
85
- ccli "给这个项目加一个命令行参数解析模块"
91
+ ## 工具
86
92
 
87
- # 一次性模式（适合脚本/管道）
88
- ccli -p "用一句话总结 src/agent/loop.ts 的作用"
93
+ | 工具 | 类型 | 说明 |
94
+ | --- | --- | --- |
95
+ | `read_file` / `list_dir` | 感知 | 读取文件（带行号）、列目录 |
96
+ | `grep` / `glob` | 感知 | 正则检索内容、按模式匹配文件 |
97
+ | `web_fetch` | 感知 | 抓取网页并转为文本 |
98
+ | `write_file` / `edit_file` | 行动 | 创建 / 覆盖、精确替换编辑（带行级 diff） |
99
+ | `bash` | 行动 | 执行 shell 命令（受权限约束，高危告警） |
100
+ | `todo_write` | 协调 | 维护多步任务清单并实时显示进度 |
101
+ | `task` | 协调 | 派生只读子代理执行聚焦调研 |
89
102
 
90
- # 指定模型 / 自动批准
91
- ccli --model claude-sonnet-4-6
92
- ccli -y "运行测试并修复失败"
93
- ```
103
+ ## 文档
94
104
 
95
- 未全局安装时用 `npm run dev -- "你的目标"`（开发）或 `node dist/index.js`（构建后）。
96
-
97
- ## 交互命令（Slash Commands）
98
-
99
- | 命令 | 说明 |
100
- |---|---|
101
- | `/help` | 显示所有命令 |
102
- | `/clear` | 清空对话历史 |
103
- | `/compact` | 压缩历史以节省上下文 |
104
- | `/model [id]` | 查看或切换模型 |
105
- | `/cost` | 本次会话 token 用量与估算成本（USD） |
106
- | `/init` | 分析项目并生成 CCLI.md |
107
- | `/commit` | 生成提交信息并 git 提交 |
108
- | `/resume` | 列出本目录的历史会话 |
109
- | `/auto` | 切换自动批准模式 |
110
- | `/permissions` | 查看权限白名单 |
111
- | `/status` | 会话状态 |
112
- | `/exit` | 退出 |
113
-
114
- 输入框中：
115
- - `!<命令>` 直接执行 shell 命令
116
- - `#<文字>` 把一条规则写入 CCLI.md（长期记忆）
117
- - `@<路径>` 引用文件内容并入消息
118
- - `Ctrl+C` 中断当前生成；连按两次退出
119
-
120
- ## 工具集
105
+ - [使用指南](https://github.com/GridGit/ai-cli/blob/main/docs/使用指南.md) —— 运行方式、交互、斜杠命令、典型工作流、常见问题、发布流程
106
+ - [架构设计](https://github.com/GridGit/ai-cli/blob/main/docs/架构设计.md) —— 设计理念、分层架构、代理循环数据流、扩展指南
121
107
 
122
- | 工具 | 类型 | 说明 |
123
- |---|---|---|
124
- | `read_file` | 感知 | 读取文件（带行号，支持分段） |
125
- | `list_dir` | 感知 | 列目录 |
126
- | `grep` | 感知 | 正则搜索代码内容 |
127
- | `glob` | 感知 | 按文件名模式查找 |
128
- | `web_fetch` | 感知 | 抓取网页转文本（需授权） |
129
- | `write_file` | 行动 | 写入/创建文件（需授权，带 diff） |
130
- | `edit_file` | 行动 | 精确替换编辑（需授权，带行级 diff） |
131
- | `bash` | 行动 | 执行 shell 命令（需授权，高危告警） |
132
- | `todo_write` | 协调 | 维护多步任务清单并实时渲染进度 |
133
- | `task` | 协调 | 派生只读子代理做聚焦调研 |
134
-
135
- ## 对齐真实 Claude Code 的高级特性
136
-
137
- 在 [`docs/差距/`](./docs/差距/) 目录中,对照真实 Claude Code 逐项补齐(每项一份规格文档 + 代码实现):
138
-
139
- - **TodoWrite 任务追踪** — 模型把多步任务拆成清单,终端实时显示 `✔/▸/○` 进度
140
- - **WebFetch** — 抓取在线文档/网页
141
- - **`@文件` 引用** — 输入 `@src/x.ts` 自动并入文件内容
142
- - **会话持久化** — `ccli -c` 续聊上次、`ccli -r [id]` 列出/恢复历史会话
143
- - **自定义斜杠命令** — `.ccli/commands/<名>.md` 即定义 `/<名>`,支持 `$ARGUMENTS`
144
- - **行级 diff 渲染** — 编辑后展示真正的 +/- diff(LCS 算法)
145
- - **子代理 / Task 工具** — 派生独立上下文的只读子代理做调研
146
- - **Hooks 生命周期钩子** — `.ccli/settings.json` 配置 `PreToolUse`(可拦截)/`PostToolUse`
147
- - **流式 Markdown 实时渲染** — 流式正文按完整行实时套用 markdown(标题/列表/代码块/行内样式)
148
- - **真实定价 `/cost`** — 按模型单价估算美元成本
149
- - **`#` 写记忆** — `#<文字>` 追加规则到 CCLI.md
150
- - **`/init`** — 让 agent 分析项目生成 CCLI.md
151
- - **`/commit`** — 让 agent 总结改动并 git 提交
152
-
153
- 尚未实施的项(MCP、图片输入、WebSearch、Vim 模式等)及理由见 [`docs/差距/09-未实施.md`](./docs/差距/09-未实施.md)。
154
-
155
- ## 架构
156
-
157
- > 完整的架构说明(设计理念、分层图、代理循环数据流、各模块职责、扩展指南)见 [`docs/架构设计.md`](./docs/架构设计.md)。
108
+ ## 本地开发
158
109
 
159
- ```
160
- src/
161
- ├── index.ts 入口：参数解析、API Key 引导、会话恢复
162
- ├── agent/
163
- │ ├── loop.ts 代理循环（核心状态机，含 Hooks 集成）
164
- │ ├── client.ts Anthropic API 流式封装
165
- │ ├── factory.ts Agent 装配（工具 + Todo + Hooks + 子代理）
166
- │ └── prompt.ts 系统提示词
167
- ├── tools/ 工具系统：filesystem / search / bash / todo / web / task
168
- ├── permissions/ 权限/授权机制
169
- ├── context/ 项目上下文扫描与索引
170
- ├── hooks/ 生命周期钩子（Pre/PostToolUse）
171
- ├── session/ 会话持久化（continue/resume）
172
- ├── commands/ 斜杠命令 + 自定义命令加载
173
- ├── config/ 配置管理
174
- ├── cli/
175
- │ ├── session.ts 交互式 REPL
176
- │ ├── headless.ts 一次性模式
177
- │ └── mentions.ts @文件引用展开
178
- └── ui/ 终端 UI（配色 / Markdown / diff / 动画）
179
-
180
- docs/ 文档
181
- ├── 主流AI-CLI工具对比说明.md
182
- └── 差距/ 与真实 Claude Code 的差距分析与实施记录
110
+ ```bash
111
+ git clone https://github.com/GridGit/ai-cli.git
112
+ cd ai-cli
113
+ npm install
114
+ cp .env.example .env # 填入密钥
115
+ npm run dev -- "你的目标" # 用 tsx 直接运行源码
116
+ npm run build # 编译到 dist/
183
117
  ```
184
118
 
185
119
  ## 许可
186
120
 
187
- MIT
121
+ [MIT](./LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gird/ccli",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "CCLI —— 代理型（Agentic）终端 AI 编程助手,支持 Anthropic 与 OpenAI 兼容后端(通义千问/DeepSeek/GLM)",
5
5
  "type": "module",
6
6
  "bin": {