xuanzhu 0.1.3 → 0.1.5

package/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2026 Oyinlola Olasunkanmi Raymond
+Copyright (c) 2026 amble311 (玄猪 XuanZhu 的改造与衍生部分)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,8 +2,18 @@
 
 > 专为终端打造的 AI 编码 Agent —— 一条 `xzh` 命令，把 AI 编程助手带进你的终端。
 
+## 快速上手
+
+```bash
+npm i -g xuanzhu    # 安装（需要 Node.js ≥ 18）
+xzh model           # 配置模型：选服务商、填 API Key
+xzh                 # 启动
+```
+
+## 简介
+
 玄猪是一个运行在终端里的全屏 AI Agent：它能读懂你的代码库、直接读写文件、执行命令、运行测试，
-并用流式输出向你展示它的每一步思考与工具调用。内核采用了codebuddy的开源代码。
+并用流式输出向你展示它的每一步思考与工具调用。内核采用了 codebuddy 的开源代码。
 
 ```
 ╭──────────────────────────────────────────────╮
@@ -17,7 +27,7 @@
 - **多模型支持**：DeepSeek、Anthropic Claude、OpenAI、Google Gemini、智谱 GLM、通义千问、Groq、Ollama，以及任意 OpenAI 兼容端点。
 - **内置工具**：读取 / 写入 / 编辑文件、列目录、glob 查找、grep 搜索、执行 shell 命令。
 - **流式响应**：实时渲染 Markdown，支持代码块，中文对齐正确。
-- **安全确认**：默认开启自动批准（`autoApprove: true`），工具直接执行；`/auto off` 可切换为写文件与执行命令逐项确认。唯一例外是读取工作区之外的敏感路径（`~/.ssh`、`.env`、`~/.xzh/config.json` 等），此时无论如何都会确认 —— 防止凭据被读进上下文并转交给模型服务商。
+- **默认全自动**：`autoApprove` 默认为 `true`，所有工具——包括写文件、执行命令、读取工作区之外的文件——都直接执行，无需逐项确认，开箱即用；`/auto off` 可切换为写文件与执行命令逐项确认。唯一的例外是读取**凭据类文件**（`~/.ssh`、`.env`、`~/.xzh/config.json`、`*.pem` 等）时会确认一次 —— 防止凭据被读进上下文并转交给模型服务商。这与是否在工作区内无关。
 - **多轮自主执行**：自动串联工具调用完成任务，可随时 `Ctrl+C` 中断。
 
 ## 环境要求
@@ -27,33 +37,35 @@
 
 ## 安装
 
-### 一键安装
+### 方式一：npm（推荐）
 
-**方式一：从源码目录安装（推荐）**
+```bash
+npm i -g xuanzhu    # 全局安装
+xzh                 # 启动
+```
 
-在仓库目录里直接执行，脚本会识别自身所在位置并**从该目录全局安装**——
-因此**不要求包已发布到 npm**：
+不想全局安装，也可以免安装试用：
 
 ```bash
-cd /path/to/xzh
-./install.sh
+npx xuanzhu
 ```
 
-**方式二：远程一键安装**
+> 若安装后提示 `xzh: command not found`，说明 npm 的全局 `bin` 目录不在 `PATH` 中，
+> 见下方「PATH 配置」。
 
-适用于包已发布到 npm、或通过环境变量给出可用源的情况：
+### 方式二：一键脚本
 
-```bash
-# Linux / macOS
-curl -fsSL https://raw.githubusercontent.com/<owner>/<repo>/main/install.sh | sh
+**Linux / macOS**
 
-# Windows（PowerShell）
-iex (irm https://raw.githubusercontent.com/<owner>/<repo>/main/install.ps1)
+```bash
+curl -fsSL https://raw.githubusercontent.com/amble311/xuanzhu/main/install.sh | sh
 ```
 
-> 上面的 `<owner>/<repo>` 请替换为实际仓库路径。
-> ⚠️ 包名为 `xuanzhu`，**目前尚未发布到 npm**，因此远程方式在发布前会报 404，
-> 请改用方式一，或用 `XZH_PACKAGE` 指定源。
+**Windows（PowerShell）**
+
+```powershell
+iex (irm https://raw.githubusercontent.com/amble311/xuanzhu/main/install.ps1)
+```
 
 脚本会检查 Node.js 版本、全局安装 `xzh`，并在需要时提示补充 PATH。
 
@@ -64,7 +76,7 @@ iex (irm https://raw.githubusercontent.com/<owner>/<repo>/main/install.ps1)
 npm config set prefix ~/.npm-global   # 然后确保 ~/.npm-global/bin 在 PATH 中
 ```
 
-### 安装脚本的环境变量
+**脚本支持的环境变量**
 
 | 变量 | 作用 |
 | --- | --- |
@@ -73,23 +85,29 @@ npm config set prefix ~/.npm-global   # 然后确保 ~/.npm-global/bin 在 PATH
 | `XZH_NPM_ARGS` | 追加给 npm 的参数，如国内镜像 `--registry=https://registry.npmmirror.com` |
 | `XZH_DRY_RUN=1` | 只打印将要执行的命令，不真正安装 |
 
-### 从源码手动安装
+### 方式三：从源码安装（开发用）
 
 ```bash
-# 安装依赖并构建
+git clone https://github.com/amble311/xuanzhu.git
+cd xuanzhu
 npm install
 npm run build
-
-# 全局链接，使 xzh 命令可用
-npm link
+npm link          # 使 xzh 命令指向本地源码
 ```
 
-安装完成后，即可在任意目录运行：
+改动源码后执行 `npm run build` 即生效（`npm link` 建立的是软链）。
+想切回正式发布的版本：
 
 ```bash
-xzh
+npm unlink -g xuanzhu && npm i -g xuanzhu
 ```
 
+### 环境要求
+
+- **Node.js ≥ 18**
+- **真实终端**：TUI 需要交互式终端，在管道、CI 或部分编辑器内置终端中无法运行
+- 首次运行会在**当前工作目录**创建 `.xuanzhu/`（项目记忆与规则），建议写入 `.gitignore`
+
 ## 快速开始
 
 ```bash
@@ -150,7 +168,7 @@ XZH_HOME=/path/to/dir xzh          # 改用 /path/to/dir/config.json
     { "id": "openai/gpt-4o", "provider": "openai", "model": "gpt-4o", "weight": 6 }
   ],
   "temperature": 0.2,
-  "maxToolRounds": 40,
+  "maxToolRounds": 200,
   "autoApprove": true,
   "intent": { "enabled": false },
   "providers": {
@@ -291,7 +309,7 @@ API Key 也可以来自环境变量，优先级低于配置文件：
 | --- | --- |
 | `.xuanzhu/memory/MEMORY.md` | 长期记忆：稳定的项目结论与约定，启动时会注入系统提示词（节选） |
 | `.xuanzhu/memory/YYYY-MM-DD.md` | 每日日志：按天追加的过程记录 |
-| `.xuanzhu/rules.md` | 项目规则，内容作为「项目级指令」注入系统提示词 |
+| `.xuanzhu/rules.md` | 项目规则，内容作为「项目级指令」注入系统提示词。**首次初始化时若项目根已有 `AGENTS.md`**，会以它的内容作为初始规则 |
 
 记忆由玄猪自行维护：
 
@@ -467,6 +485,44 @@ npm run typecheck   # 类型检查
 node bin/xzh.js     # 本地运行
 ```
 
+### 发布新版本
+
+```bash
+./release.sh                         # 版本尾号 +1（0.1.4 → 0.1.5）
+./release.sh minor                   # 0.1.4 → 0.2.0
+./release.sh 1.0.0                   # 指定版本
+XZH_RELEASE_DRY_RUN=1 ./release.sh   # 先演练一遍，不做任何写入
+```
+
+脚本会依次完成：**版本号 +1 → `npm publish` → 等待 registry 同步 → 提交并推送 GitHub
+→ 更新本机全局安装**。
+
+之所以需要脚本，是因为这条链路有几个反直觉的地方：`npm publish` 返回成功**不等于**
+registry 已可见（npm 有 staging 阶段，期间 `npm view` / `npm install` 会报 `notarget`），
+而版本号、GitHub 提交、npm 包三者又必须保持一致。脚本把它们串起来并自动等待与重试。
+
+| 环境变量 | 作用 |
+| --- | --- |
+| `XZH_RELEASE_DRY_RUN=1` | 只演练，不改版本、不发布、不推送 |
+| `XZH_RELEASE_YES=1` | 跳过发布前的确认提示 |
+| `XZH_RELEASE_SKIP_GIT=1` | 不推送 GitHub |
+| `XZH_RELEASE_SKIP_LOCAL=1` | 不更新本机全局安装 |
+| `XZH_RELEASE_WAIT=<秒>` | 等待 registry 同步的上限（默认 300） |
+
+## 致谢
+
+本项目站在前人的开源工作上，特别感谢：
+
+- **[CodeBuddy](https://github.com/olasunkanmi-SE/codebuddy)** —— 作者
+  [Oyinlola Olasunkanmi Raymond](https://github.com/olasunkanmi-SE)。
+  玄猪由该项目改造而来（移除编辑器依赖、改为纯粹的终端形态），
+  并依 MIT 许可**保留其原始版权声明**。
+- **[Playwright](https://github.com/microsoft/playwright)** —— 由 Microsoft 开源。
+  内置的 `playwright` 技能基于它实现浏览器自动化与端到端测试。
+
+同时也感谢所有直接与间接依赖的开源项目，以及 npm 生态中的众多工具
+（完整清单见 `package.json`）。
+
 ## License
 
 MIT