@huicai/cli 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HuiCai AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# huicai CLI —— 终端智能体
+
+在你电脑的终端里运行智能体：**循环与工具都在本机**，平台的 OpenAI 兼容 `/v1` 只做模型推理与计费。
+智能体能真正地读写你的项目文件、搜索、执行 shell 命令来完成任务。
+
+> 与「平台云端智能体」互补：云端智能体在服务端跑工具（MCP/沙箱/工作区）；本 CLI 让智能体在**你的真实仓库**里干活。
+
+## 直接运行
+
+纯 Node.js（ESM），需 Node ≥ 18（推荐 20+）。
+
+```bash
+cd huicai-cli
+npm install         # 可选：装 ink+react 以启用富 TUI（不装则自动回退零依赖 REPL）
+npm link            # 安装全局 huicai 命令（或：node bin/huicai.js）
+```
+
+核心链路**零第三方运行时依赖**（`--plain` 或未装 ink 时，只用 Node 内置模块即可跑）。
+富 TUI（`--tui`，默认在 TTY 下启用）需 `ink`+`react`（package.json 已声明）；缺失时自动回退到 readline REPL。
+
+## 配置
+
+```bash
+huicai login          # 填平台网关地址 → 浏览器授权（自动打开，确认即可）→ 保存令牌
+huicai login --paste  # 改为手动粘贴已有 API 令牌（离线/无浏览器环境）
+# 或用环境变量：
+export HUICAI_BASE_URL=https://<你的网关地址>
+export HUICAI_API_KEY=sk-huicai-xxxxx
+export HUICAI_MODEL=<模型id>       # 用 `huicai models` 查看
+```
+
+- **浏览器授权（推荐）**：`huicai login` 发起设备码流，打开 Web 端 `/device` 页，登录用户确认后自动为该终端铸造令牌回传 CLI，无需手动粘贴。
+  - 需服务端配置 Web 端授权页地址：Nacos `huicai.device.verification-uri`（如 `https://app.example.com/device`）。未配置时 CLI 会提示你手动打开 Web 端 `/device` 页并输入授权码。
+- **手动令牌**：也可在平台「API 令牌」页创建后 `huicai login --paste` 粘贴。
+- `/v1` 用令牌做 Bearer 鉴权（豁免国密签名）。配置存于 `~/.huicai/config.json`（权限 0600）。
+
+## 使用
+
+```bash
+huicai                          # 进入交互式会话（当前目录即项目根）
+huicai "把 utils 里的时间函数抽成独立模块并加测试"
+huicai -p "运行 npm test 并总结失败原因" --yolo   # 一次性/CI 模式
+huicai -p "分析" --output-format json             # 结构化输出（脚本集成：result/usage/session_id）
+cat error.log | huicai -p "解释这段报错"           # 管道 stdin 自动作为上下文
+huicai --agent <shareToken>     # 采用某已发布智能体的人格（系统提示词+模型），工具仍在本机执行
+huicai -c                       # 继续当前目录最近一次会话
+huicai -r                       # 从历史会话中选择恢复
+huicai sessions                 # 列出历史会话
+huicai models                   # 列出可用模型（含 agent-/workflow-/datahuman- 伪模型）
+```
+
+### 交互增强
+
+- **`@文件` 引用**：消息里写 `@src/app.js`，文件内容自动展开给模型（目录则展开清单）。
+- **`!命令` 直通**：`!git log -3` 直接在本机执行，输出进入对话上下文，不消耗模型调用。
+- **边跑边补充**：模型工作中继续输入回车即**排队**，工具轮间隙自动注入本回合（无需等待/打断）。
+- **任务清单**：多步骤任务模型会用 `todo_write` 列计划并实时更新（TUI 渲染 ☐/◐/☑ 面板）。
+- **输入历史**：上下键翻阅历史输入（按项目目录持久化到 `~/.huicai/history.json`）。
+- **`Esc` 中断当前回合**（TUI）；`Ctrl+C` 中断/退出。
+
+### 自定义斜杠命令
+
+`<项目>/.huicai/commands/*.md` 或 `~/.huicai/commands/*.md`，文件名即命令名，内容为提示词模板，
+`$ARGUMENTS` 替换为命令参数；可选 frontmatter 写 `description:`。例如 `.huicai/commands/review.md`：
+
+```markdown
+---
+description: 审查最近一次提交
+---
+请审查 $ARGUMENTS 的改动：先 !git show 查看 diff，指出问题并给修复建议。
+```
+
+### 会话 resume
+
+对话自动保存到 `~/.huicai/sessions/`（含系统提示词与每一轮消息，权限 0600），**按项目目录归属**。
+
+```bash
+huicai -c ["prompt"]     # 继续「当前目录」最近一次会话（可带一句新指令）
+huicai -r                # 列出当前目录历史会话，选编号恢复
+huicai resume <id>       # 恢复指定会话（id 见 huicai sessions）
+huicai sessions [-a]     # 列出会话（-a 跨所有目录）
+huicai -c -p "继续修" --yolo   # 非交互续接（CI）
+```
+
+- 恢复后会显示上次回复摘要帮你接上下文；后续对话带完整历史（真正的多轮记忆）。
+- 交互中 `/clear` 开启**新会话**（旧会话仍留存可恢复）；`/sessions` 就地查看历史。
+- 恢复默认沿用该会话原模型；`-m` / `--agent` 可覆盖。
+
+### 采用平台智能体人格（`--agent`）
+
+`huicai --agent <id>` 会拉取某已发布智能体的**人格**（系统提示词 + 其配置的模型/温度），让 CLI「扮演」该智能体，
+但**工具依旧在你本机执行**（读写文件/shell）。`<id>` 用智能体的分享令牌或 `agent-<token>`（见 `huicai models`）。
+未显式 `-m` 时自动采用该智能体配置的模型。适合把平台上调好的「代码审查员」「重构助手」等直接搬到终端里干活。
+
+交互中的斜杠命令（REPL 与 TUI 共用一套注册表）：
+`/help /model /models /clear /compact /cost /status /sessions /yolo /cwd /init /mcp /exit` + 自定义命令。
+`/init` 会让智能体实际调研项目后生成/完善 `HUICAI.md`（非静态模板）；`/status` 显示版本/模型/会话/MCP/权限规则。
+
+## 内置本机工具
+
+| 工具 | 说明 | 授权 |
+|---|---|---|
+| `read_file` / `list_files` / `glob` / `grep` | 读(带行号)/列/查找/搜索（grep 支持 ignore_case/files_only） | 自动放行（只读） |
+| `write_file` / `edit_file` | 写文件 / 精确替换（仅项目目录内） | 需授权 |
+| `run_bash` | 执行 shell 命令（超时整进程组击杀；Windows 走 cmd） | 需授权 |
+| `fetch_url` | 抓取网页/接口（HTML 自动转纯文本），查在线文档 | 需授权 |
+| `todo_write` | 维护任务清单（TUI 实时渲染进度） | 自动放行 |
+| `dispatch_agent` | 委派子任务给隔离上下文的只读子智能体 | 自动放行（只读） |
+| `mcp__<服务>__<工具>` | 本地 MCP 服务提供的工具 | 按 readOnlyHint（写型需授权） |
+
+**执行策略**：同一轮里连续的只读工具调用**并行执行**（结果仍按序回灌）；单条工具输出超长自动**截断保头尾**，
+防止撑爆上下文；中断（Esc/Ctrl+C）时为未执行的调用合成占位结果，保证消息协议不被破坏、会话可无缝续聊。
+
+### 本地 MCP 服务
+
+在 `~/.huicai/mcp.json` 配置本地 MCP 服务（通用 mcpServers 格式），启动时自动连接（stdio）并把其工具接入智能体：
+
+```json
+{
+  "mcpServers": {
+    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/你的/目录"] }
+  }
+}
+```
+
+工具名暴露为 `mcp__filesystem__<工具>`；只读工具（`readOnlyHint`）自动放行，写型需授权。未配置该文件时完全无副作用。
+
+### 子智能体（dispatch_agent）
+
+内置 `dispatch_agent` 工具：把明确、独立的子任务交给「隔离上下文 + 只读工具」的子智能体自主完成，只回传结论——
+让主线程上下文保持精简，适合并行/发散的调研、检索、分析。子智能体只读（写/执行被拒），最多再委派一层。
+
+### 上下文记忆（长期 + 短期）
+
+- **长期记忆**：模型经内置 `memory_write` 工具把值得跨会话记住的信息（偏好/项目事实/结论）写入
+  `~/.huicai/memory/`（按项目归属），**新会话自动注入系统提示词**。`/memory` 查看、`/memory clear` 清空；
+  配置 `memory:false`（或 `HUICAI_MEMORY=0`）关闭。
+- **短期记忆**：会话完整消息 + 下述非破坏式压缩摘要。
+
+### 上下文自动压缩（非破坏式）
+
+双触发：累计字符超阈值（约 16k tokens），或上一轮**真实 `prompt_tokens`** 超限（默认 80k，
+`autoCompactTokens` 可调）。**摘要独立存储在会话的 compaction 状态里，原对话消息与页面显示完全不变**——
+只是发给模型的上下文换成「system + 摘要 + 最近几轮」的视图。以用户消息为切割边界，绝不拆散工具调用与其结果。
+`/compact` 可随时手动压缩（同样不影响已显示内容）。
+
+### 平台编排对话（分享页同款，CLI 直连）
+
+`huicai -m agent-xxx`（或 workflow-/datahuman- 伪模型）自动进入**平台编排模式**：不传本机工具、纯流式多轮，
+即智能体/业务数字人/工作流分享页的对话能力（数字人自然语言查数、工作流参数启动）。上下文压缩/思考过程展示同样可用。
+
+### 思考过程流式展示
+
+模型的 reasoning 增量实时可见：REPL 灰字 `[思考]`、TUI 动态区 `✦ 思考`（正文开始自动收起）。
+默认开启；配置 `showReasoning:false`（或 `HUICAI_REASONING=0`）关闭。
+
+### 可靠性
+
+- 模型请求遇 429/5xx/网络错在首字节前**自动指数退避重试**（尊重 `Retry-After`，最多 2 次）。
+- 流式响应 90s 无数据由**停滞看门狗**中止（不再挂死），可直接重发。
+- 单回合最大工具轮数默认 60（`--max-turns` / `HUICAI_MAX_TURNS` / 配置 `maxTurns` 可调）。
+
+## 富 TUI（ink）
+
+TTY 下默认启用 ink + React 全屏界面：已定稿对话记录 + 流式正文、任务清单面板（☐/◐/☑）、思考 spinner、
+彩色工具卡片、内联授权提示（含高风险命令红色警示）、底部状态栏（模型/token/上下文规模/排队数/yolo）。
+输入行支持**光标编辑**（←→、Ctrl+A/E/U/K/W）与**上下键历史**；忙时输入自动排队；`Esc` 中断。
+`--plain` 强制普通 REPL；未安装 ink 时自动回退。
+用 `React.createElement` 编写，**无 JSX 构建步骤**，`npm install` 后 `node` 直接跑。
+
+## VS Code / Cursor 集成
+
+见 [`vscode/`](vscode/README.md)：纯 JS 扩展（无需构建），三项深度集成：
+- **诊断上下文**：把 Problems 诊断 + 当前文件/选区经环境变量注入智能体（`HUICAI_IDE_FILE`/`SELECTION`/`DIAGNOSTICS`）。
+- **内联 diff 审阅**：智能体写文件时，CLI 经本地服务把改动交扩展弹**原生 diff + 应用/拒绝**（`WorkspaceEdit`，可撤销）；未在扩展终端里则直接写盘。
+- **侧边栏面板**：快捷操作 + 最近会话列表（点击恢复）。
+含快捷键、右键菜单。CLI 侧对应 `src/ide.js`（写入提案）与 `--file`/`--prompt`、`HUICAI_IDE_*` 环境变量。
+
+授权提示：`y` 允许一次 · `a` 本会话都允许该工具 · `A` **永久允许**（把规则写入项目 `.huicai/settings.json`）·
+回车/`n` 拒绝（可附文字作为反馈回灌模型）。高风险命令（`rm -rf`、`sudo`、强推等）会红色警示。
+`--yolo` 或 `/yolo` 全自动放行（谨慎，尤其在陌生仓库）。
+
+### 权限允许规则（settings.json）
+
+全局 `~/.huicai/settings.json` 与项目 `<项目>/.huicai/settings.json` 合并生效：
+
+```json
+{ "permissions": { "allow": ["run_bash(git *)", "run_bash(npm test*)", "fetch_url(https://docs.example.com*)"] } }
+```
+
+规则为 `工具名` 或 `工具名(通配模式)`（`run_bash` 匹配命令、`fetch_url` 匹配 URL、文件类匹配路径）。
+命中规则的调用免审批；审批时按 `A` 即自动生成并写入合适的规则（如 `run_bash(git *)`）。
+
+## 项目上下文
+
+启动时自动注入：工作目录、OS、Git 分支与未提交改动、顶层文件；若存在 `HUICAI.md`（或 `AGENTS.md`/`CLAUDE.md`）
+则作为项目说明加入系统提示词；`~/.huicai/HUICAI.md` 作为**全局用户说明**（跨项目个人偏好）一并注入。
+用 `/init` 让智能体调研项目后自动生成/完善 HUICAI.md。
+
+## 安全
+
+- 写/执行工具默认需要人工授权；只读自动放行。
+- 写/编辑被限制在**当前项目目录**内（防误伤系统路径）。
+- 令牌文件 0600；日志不打印令牌。
+- ⚠ `--yolo` 会跳过所有确认，仅在你信任的仓库使用。
+
+## 架构（一图）
+
+```
+终端 huicai (本机)
+  └─ Agent 循环: messages + 本机 tools ──POST /v1/chat/completions──▶ HuiCai 平台(模型/计费)
+        ▲                                    │ 返回 tool_calls / 流式增量
+        └────── 本机执行工具(读写文件/shell) ◀┘
+```
+
+## 后续（Roadmap）
+
+- ✅ `huicai login` 设备码浏览器授权流（免手填令牌）
+- ✅ `--agent <id>` 采用平台智能体 persona，工具仍在本机执行
+- ✅ 会话 resume（`-c` / `-r` / `resume <id>` / `sessions`，按项目自动保存）
+- ✅ 本地 MCP 客户端（stdio）、客户端子智能体（dispatch_agent）、上下文自动压缩
+- ✅ ink + React 富 TUI（可回退零依赖 REPL）
+- ✅ VS Code / Cursor 扩展：诊断上下文 + 内联 diff 审阅 + 侧边栏面板 + SCM 视图 + 多文件批量 diff + 内嵌对话面板(webview)
+- ✅ v0.2 重构：todo 任务清单 / 只读工具并行 / @文件·!命令 / 自定义斜杠命令 / settings.json 权限规则(+A 永久允许)
+  / 请求重试+停滞看门狗 / token 感知压缩+/compact / 排队补充指令 / TUI 光标编辑+持久历史+Esc 中断
+  / fetch_url / headless JSON 输出+管道 stdin / 中断协议修复
+- CLI 功能面已覆盖主流 AI 编程智能体核心能力