qianshou 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qianshou Contributors
+
+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,396 @@
+<h1 align="center">千手</h1>
+
+<p align="center">
+  <strong>面向办公人士的 AI 智能体应用。</strong><br>
+  理解项目文档、代码库。规划复杂任务。自主执行。<br>
+  你的终端 AI 队友。
+</p>
+
+<p align="center">
+  <a href="https://zyinfo.pro/qianshou/">📖 官方文档</a> •
+  <a href="#安装">🚀 快速开始</a> •
+  <a href="#配置认证">⚙️ 配置指南</a>
+</p>
+
+---
+
+## 目录
+
+- [什么是千手](#什么是千手)
+- [核心功能](#核心功能)
+- [安装](#安装)
+- [配置认证](#配置认证)
+- [快速开始](#快速开始)
+- [使用方法](#使用方法)
+- [实验性功能](#实验性功能)
+
+---
+
+## 什么是千手
+
+千手是一款运行在终端中的**智能体编码工具**。与传统的代码补全工具不同，千手能够理解你的整个代码库，规划复杂的多步骤任务，并自主执行。
+
+把它当作一个 AI 队友，它可以：
+- 阅读并理解大规模项目
+- 将复杂需求分解为可执行的步骤
+- 编写、修改和重构跨多个文件的代码
+- 运行终端命令并管理 Git 工作流
+- 解释代码逻辑并生成文档
+
+**了解更多：** [https://zyinfo.pro/qianshou/](https://zyinfo.pro/qianshou/)
+
+---
+
+## 核心功能
+
+### 🧠 智能体编码
+
+千手作为一个**自主智能体**运行，而不仅仅是一个被动的助手。当你给它一个高层次的目标，比如"添加 OAuth 用户认证"时，它会：
+
+1. **理解意图** - 分析你的自然语言请求
+2. **扫描上下文** - 阅读相关文件并理解项目结构
+3. **制定计划** - 将任务分解为清晰、可执行的步骤
+4. **执行** - 在你的批准下实施每个步骤
+5. **迭代** - 报告进度并在需要时寻求澄清
+
+### 📚 代码库级理解
+
+支持 **200K+ token 上下文窗口**，千手可以一次性分析整个项目。它理解：
+- 项目结构和模块依赖关系
+- 编码模式和设计约定
+- 跨文件关系和架构决策
+
+### 🔧 深度代码分析
+
+- **解释复杂代码** - 获取函数、算法和逻辑流的详细说明
+- **追踪函数调用** - 跟踪代码库中的执行路径
+- **识别问题** - 检测性能瓶颈、安全漏洞和潜在错误
+- **智能重构** - 执行大规模、跨文件的代码转换
+
+### ⚡ 工作流自动化
+
+千手与你的开发工作流无缝集成：
+
+- **运行终端命令** - 执行 `npm install`、运行测试、构建 Docker 镜像
+- **Git 集成** - 搜索提交历史、解决合并冲突、生成提交信息
+- **测试生成** - 自动创建全面的单元测试和集成测试
+- **文档生成** - 生成 API 文档、代码注释和 README 文件
+
+### 🔌 可扩展架构
+
+- **MCP 协议** - 通过模型上下文协议连接外部工具和 API
+- **自定义技能** - 编写自己的命令和工作流
+- **插件系统** - 通过社区插件扩展功能
+- **IDE 无关** - 适用于任何编辑器（VS Code、JetBrains、Vim 等）
+
+### 🌐 浏览器自动化
+
+千手支持浏览器自动化功能，可以与 Chrome 浏览器深度集成：
+
+- **网页交互** - 自动点击元素、填写表单、捕获截图
+- **标签页管理** - 读取和控制浏览器标签页
+- **控制台日志** - 读取浏览器控制台日志和网络请求
+- **OAuth 认证** - 支持需要登录状态的网站操作
+
+**启用方式：**
+```bash
+# 使用 --chrome 参数启动
+qianshou --chrome
+
+# 或设置环境变量
+export QS_ENABLE_CFC=1
+qianshou
+```
+
+**前提条件：**
+- 需要安装 [千手 Chrome 扩展程序](https://clau.de/chrome)
+- 支持 Chrome、Brave、Edge 等 Chromium 浏览器
+
+---
+
+## 安装
+
+> **详细安装指南：** [https://zyinfo.pro/qianshou/](https://zyinfo.pro/qianshou/)
+
+### Windows 安装
+
+打开 Windows 终端中的 PowerShell 终端（右键按 Windows 按钮，点击「终端」），然后依次执行：
+
+```powershell
+# 安装 Git（或参考 https://git-scm.com/install/windows 用其他办法安装）
+winget install --exact --source winget --id Git.Git
+
+# 安装 Node.js（或参考 https://nodejs.org/zh-cn/download 用其他办法安装）
+winget install --exact --source winget --id OpenJS.NodeJS
+
+# 设置脚本执行策略
+Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+
+# 关闭终端窗口，新开一个终端窗口，然后安装千手
+npm install -g qianshou --registry=https://registry.npmmirror.com
+
+# 初始化配置
+node --eval "
+const homeDir = os.homedir();
+const filePath = path.join(homeDir, '.claude.json');
+if (fs.existsSync(filePath)) {
+  const content = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  fs.writeFileSync(filePath, JSON.stringify({ ...content, hasCompletedOnboarding: true }, null, 2), 'utf-8');
+} else {
+  fs.writeFileSync(filePath, JSON.stringify({ hasCompletedOnboarding: true }), 'utf-8');
+}"
+```
+
+### macOS/Linux 安装
+
+```bash
+npm install -g qianshou
+```
+
+### 系统要求
+
+- **运行时**: [Node.js](https://nodejs.org/) 或 [Bun](https://bun.sh) >= 1.3.11
+- **操作系统**: macOS、Linux 或 Windows（推荐使用 WSL）
+- **认证**: 所选提供商的 API 密钥
+
+---
+
+## 配置认证
+
+> **更多配置示例：** [https://zyinfo.pro/qianshou/](https://zyinfo.pro/qianshou/)
+
+千手原生支持多个 AI 提供商。设置相应的环境变量即可切换提供商。
+
+### 智谱 GLM（推荐）
+
+```bash
+export QS_AUTH_TOKEN="你的智谱API密钥"
+export QS_BASE_URL=https://open.bigmodel.cn/api/anthropic
+export API_TIMEOUT_MS="3000000"
+export QS_DISABLE_NONESSENTIAL_TRAFFIC=1
+export QS_SMALL_MODEL="glm-4.5-air"
+export QS_MIDDLE_MODEL="glm-4.7"
+export QS_BIG_MODEL="glm-5.1"
+export QS_MODEL="glm-5.1"
+export ENABLE_TOOL_SEARCH=false
+
+# 进入你的工作目录
+cd 你的工作目录
+
+# 启动千手（bypassPermissions 模式自动批准所有操作）
+qianshou --permission-mode bypassPermissions
+```
+
+### 阿里云通义千问
+
+```bash
+export QS_AUTH_TOKEN="你的阿里云API密钥"
+export QS_BASE_URL="https://coding.dashscope.aliyuncs.com/apps/anthropic"
+export API_TIMEOUT_MS=600000
+export QS_MODEL="qwen-max"
+export QS_BIG_MODEL="qwen-max"
+export QS_MIDDLE_MODEL="qwen-plus"
+export QS_SMALL_MODEL="qwen-turbo"
+
+qianshou --permission-mode bypassPermissions
+```
+
+### DeepSeek
+
+```bash
+export QS_BASE_URL=https://api.deepseek.com/anthropic
+export QS_AUTH_TOKEN=sk-你的DeepSeek密钥
+export API_TIMEOUT_MS=600000
+export QS_MODEL=deepseek-chat
+export QS_SMALL_FAST_MODEL=deepseek-chat
+export QS_DISABLE_NONESSENTIAL_TRAFFIC=1
+
+qianshou --permission-mode bypassPermissions
+```
+
+### 桌面办公版
+
+如需处理 Word、Excel、PDF 等办公文档，添加以下配置：
+
+```bash
+export QS_OFFICE=1
+qianshou --permission-mode bypassPermissions
+```
+
+### 创建启动脚本
+
+建议保存为启动脚本（Linux/macOS: `.sh`，Windows: `.bat`）方便使用：
+
+**Linux/macOS (qianshou.sh):**
+```bash
+#!/bin/bash
+export QS_AUTH_TOKEN="你的密钥"
+export QS_BASE_URL="https://open.bigmodel.cn/api/anthropic"
+export QS_MODEL="glm-5.1"
+export QS_BIG_MODEL="glm-5.1"
+export QS_MIDDLE_MODEL="glm-4.7"
+export QS_SMALL_MODEL="glm-4.7"
+cd "$1"
+qianshou --permission-mode bypassPermissions
+```
+
+**Windows (qianshou.bat):**
+```batch
+@echo off
+set QS_AUTH_TOKEN=你的密钥
+set QS_BASE_URL=https://open.bigmodel.cn/api/anthropic
+set QS_MODEL=glm-5.1
+set QS_BIG_MODEL=glm-5.1
+set QS_MIDDLE_MODEL=glm-4.7
+set QS_SMALL_MODEL=glm-4.7
+cd /d %1
+qianshou --permission-mode bypassPermissions
+```
+
+### AGENTS.md 配置
+
+你可在项目根目录创建 `AGENTS.md` 文件，帮助 AI 更好地了解你的项目。
+
+---
+
+## 快速开始
+
+### 三步启动
+
+**第一步：安装千手**（见上方[安装](#安装)章节）
+
+**第二步：配置认证**（见上方[配置认证](#配置认证)章节）
+
+**第三步：启动使用**
+
+```bash
+# 进入你的工作目录
+cd 你的工作目录
+
+# 启动千手
+qianshou --permission-mode bypassPermissions
+
+# 或使用自动确认模式
+qianshou --permission-mode bypassPermissions
+```
+
+### 常用启动参数
+
+| 参数 | 说明 |
+|------|------|
+| `--permission-mode bypassPermissions` | 自动批准所有操作（适合日常使用） |
+| `--auto-run` | 自动运行模式，无需确认每个命令 |
+| `--chrome` | 启用浏览器自动化模式 |
+| `-p "提示词"` | 单次执行模式，直接运行命令 |
+
+### 使用技巧
+
+**粘贴多行内容：**
+- 按 `Ctrl+G` 打开文本框，粘贴内容后保存关闭
+- 或将内容写入文件，使用 `@文件名` 引用
+
+**参考文档：** [https://zyinfo.pro/qianshou/](https://zyinfo.pro/qianshou/)
+
+---
+
+## 使用方法
+
+### 交互式 REPL
+
+```bash
+qianshou --permission-mode bypassPermissions
+```
+
+### 对话示例
+
+**实现新功能：**
+```
+你: 添加一个用户注册的 REST API 端点
+
+Qianshou: 我来帮你添加用户注册端点。让我先检查你的项目结构...
+
+[阅读文件，分析代码库]
+
+我将创建以下内容：
+1. POST /api/users/register 端点
+2. 用户验证模式
+3. 用户的数据库模型
+4. 端点的单元测试
+
+我可以继续吗？
+```
+
+**调试问题：**
+```
+你: 上传文件时出现 500 错误。这是堆栈跟踪...
+
+Qianshou: 查看错误和你的代码，问题似乎出现在文件上传处理程序中。
+问题在第 42 行，缓冲区大小处理不当。让我修复这个问题...
+```
+
+**重构代码：**
+```
+你: 重构认证模块以使用 JWT 令牌
+
+Qianshou: 我将重构你的认证模块以使用 JWT。这需要：
+1. 安装 jsonwebtoken 包
+2. 创建 JWT 工具函数
+3. 更新登录/登出处理程序
+4. 添加令牌验证中间件
+
+[继续重构]
+```
+
+---
+
+## 实验性功能
+
+`build:dev:full` 构建启用了 54 个实验性功能标志。亮点包括：
+
+### 交互与 UI
+- **ULTRAPLAN** - 远程多智能体规划
+- **ULTRATHINK** - 用于复杂推理的深度思考模式
+- **VOICE_MODE** - 按住说话语音输入
+- **TOKEN_BUDGET** - 使用跟踪和警告
+- **HISTORY_PICKER** - 交互式提示历史
+- **QUICK_SEARCH** - 快速提示搜索
+
+### 智能体、记忆与规划
+- **BUILTIN_EXPLORE_PLAN_AGENTS** - 内置智能体预设
+- **VERIFICATION_AGENT** - 任务验证
+- **AGENT_TRIGGERS** - 后台自动化
+- **EXTRACT_MEMORIES** - 自动记忆提取
+- **TEAMMEM** - 团队记忆文件
+
+### 工具与基础设施
+- **BRIDGE_MODE** - IDE 远程控制桥接
+- **BASH_CLASSIFIER** - 智能权限决策
+- **MCP_RICH_OUTPUT** - 增强的 MCP 输出
+
+### 浏览器集成
+- **Claude in Chrome** - Chrome 浏览器自动化
+  - 支持自动点击、表单填写、截图等功能
+  - 可读取控制台日志和网络请求
+  - 适用于需要登录状态的网站操作
+  - 需要 [Chrome 扩展程序](https://clau.de/chrome) 支持
+
+**启用浏览器模式：**
+```bash
+# 方式一：使用 --chrome 参数
+qianshou --chrome
+
+# 方式二：设置环境变量
+export QS_ENABLE_CFC=1
+qianshou
+```
+
+---
+
+## 相关链接
+
+- **官方文档：** [https://zyinfo.pro/qianshou/](https://zyinfo.pro/qianshou/)
+- **GitHub 仓库：** [https://github.com/yourusername/qianshou](https://github.com/yourusername/qianshou)
+
+---
+
+**用 ❤️ 构建，为想要从 AI 工具中获得更多功能的开发者服务。**