|
1 | | -# CLAUDE.md |
2 | | - |
3 | | -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
4 | | - |
5 | | -# 项目概述 |
6 | | - |
7 | | -这是一个通过编程试验 Node.js 对进程调度 bash 行为的实验项目。 |
8 | | - |
9 | | -## 项目目标 |
10 | | - |
11 | | -探索和研究 Node.js 如何创建和管理子进程来执行 bash/shell 命令，包括： |
12 | | -- 使用 `child_process` 模块（`spawn`, `exec`, `fork` 等）创建 bash 进程 |
13 | | -- 研究进程间的通信机制（stdin, stdout, stderr） |
14 | | -- 测试不同平台（Windows/Linux/Mac）下的 bash 行为差异 |
15 | | -- 分析进程生命周期和信号处理 |
16 | | - |
17 | | -## 技术栈 |
18 | | - |
19 | | -- **运行时**: Node.js |
20 | | -- **核心模块**: `child_process`, `events`, `stream` |
21 | | -- **目标**: bash/shell 进程 |
22 | | - |
23 | | -## 开发指南 |
24 | | - |
25 | | -### 运行测试脚本 |
26 | | -read [PATH hints](./winfix.md) to set bash exprot PATH |
27 | | -```bash |
28 | | -# 运行某个测试脚本（具体取决于项目中的文件） |
29 | | -node <script-name>.js |
30 | | - |
31 | | -# 使用 npm 运行（如果有 package.json） |
32 | | -npm test |
33 | | -npm start |
34 | | -``` |
35 | | - |
36 | | -# **AI助理的修改后可以不运行，但至少检查一下编译情况** |
37 | | -# **AI助理的修改代码后不要自动commit，需要用户查阅同意再commit** |
38 | | - |
39 | | -# **当出现连续重试3次也无法修正的编译或者变更失败的错误时，停下来，让用户协助决策** |
40 | | -# **优先考虑用工具regionConstrainedEdit再考虑工具editFile** |
41 | | - |
42 | | -### 关键 API |
43 | | - |
44 | | -- `child_process.spawn()` - 启动新进程 |
45 | | -- `child_process.exec()` - 执行 shell 命令 |
46 | | -- `child_process.fork()` - 创建 Node.js 子进程 |
47 | | -- `stdio` 流配置 - 进程间通信 |
48 | | -- 进程信号处理 - SIGTERM, SIGKILL 等 |
49 | | - |
50 | | -### 平台注意事项 |
51 | | - |
52 | | -在 Windows (MINGW64) 环境下，bash 可通过 Git Bash 或 WSL 提供，需要注意： |
53 | | -- 路径分隔符差异（`\` vs `/`） |
54 | | -- 可执行文件查找机制 |
55 | | -- shell 环境变量的继承 |
| 1 | +# Closer Code - AI 助理项目级提示词 |
| 2 | + |
| 3 | +本文件为 AI 助理（Claude Code、Closer 等）提供在处理本项目时需要遵循的指导原则。 |
| 4 | + |
| 5 | +## 项目本质 |
| 6 | + |
| 7 | +**Closer Code** 是一个 AI 编程助理 CLI 工具，通过对话式 AI 帮助开发者完成编程任务。 |
| 8 | + |
| 9 | +**核心机制**： |
| 10 | +- 使用 `@anthropic-ai/sdk` 的 `betaZodTool` 定义工具 |
| 11 | +- 通过 `toolRunner` 自动处理工具调用循环 |
| 12 | +- 支持流式响应和实时工具执行 |
| 13 | +- 集成 MCP (Model Context Protocol) 扩展能力 |
| 14 | + |
| 15 | +## 项目架构理解 |
| 16 | + |
| 17 | +### 关键模块 |
| 18 | + |
| 19 | +``` |
| 20 | +src/ |
| 21 | +├── conversation/core.js # 对话主控制器 |
| 22 | +├── conversation/tool-executor.js # 工具执行引擎 |
| 23 | +├── conversation/stream-handler.js # 流式响应处理 |
| 24 | +├── tools.js # 工具定义（betaZodTool） |
| 25 | +├── skills/ # 技能系统 |
| 26 | +│ ├── registry.js # 技能发现和加载 |
| 27 | +│ └── conversation-state.js # 技能状态管理 |
| 28 | +├── commands/slash-commands.js # 斜杠命令 |
| 29 | +├── ai-client.js # Anthropic AI 客户端 |
| 30 | +├── ai-client-openai.js # OpenAI AI 客户端 |
| 31 | +├── bash-runner.js # Bash 命令执行器 |
| 32 | +└── config.js # 配置管理 |
| 33 | +``` |
| 34 | + |
| 35 | +### 工具系统设计 |
| 36 | + |
| 37 | +**重要**: 项目使用 `@anthropic-ai/sdk` 的官方工具定义方式： |
| 38 | +- 所有工具使用 `betaZodTool` 定义 |
| 39 | +- 使用 Zod schema 进行输入验证 |
| 40 | +- SDK 自动处理工具调用循环（无需手工解析） |
| 41 | +- 工具定义在 `src/tools.js` 中 |
| 42 | + |
| 43 | +**内置工具**: bash, readFile, writeFile, editFile, searchFiles, searchCode, listFiles, skillDiscover, skillLoad 等 |
| 44 | + |
| 45 | +### 技能系统 |
| 46 | + |
| 47 | +**技能目录**: |
| 48 | +- 全局: `~/.closer-code/skills/` |
| 49 | +- 项目: `.closer-code/skills/` |
| 50 | + |
| 51 | +**技能格式**: `skill-name/SKILL.md` (Markdown + YAML front-matter) |
| 52 | + |
| 53 | +**可用技能**: |
| 54 | +- `relax_master` - 帮助用户放松 |
| 55 | +- `skill-author` - 帮助创建技能 |
| 56 | + |
| 57 | +## AI 助理工作规范 |
| 58 | + |
| 59 | +### 代码修改原则 |
| 60 | + |
| 61 | +**1. 工具选择优先级**: |
| 62 | +``` |
| 63 | +regionConstrainedEdit > editFile > writeFile |
| 64 | +``` |
| 65 | + |
| 66 | +- `regionConstrainedEdit`: 精确的区域编辑（推荐） |
| 67 | +- `editFile`: 简单的全文替换 |
| 68 | +- `writeFile`: 完整重写文件 |
| 69 | + |
| 70 | +**2. 文件操作规范**: |
| 71 | +- ✅ **写入后不要验证**: 工具已返回明确的成功/失败信息 |
| 72 | +- ✅ **假设成功**: 除非工具返回错误 |
| 73 | +- ❌ **不要用 readFile 验证**: 浪费 token |
| 74 | + |
| 75 | +**3. Bash 使用规范**: |
| 76 | +- ✅ 用于: 测试、构建、Git 操作、系统操作 |
| 77 | +- ❌ 避免: 文件读写、代码搜索（使用专用工具） |
| 78 | + |
| 79 | +**4. 错误处理**: |
| 80 | +- 连续重试 3 次仍失败 → 停下来请求用户协助 |
| 81 | +- 提供详细的错误信息和修复建议 |
| 82 | + |
| 83 | +### Git 提交规范 |
| 84 | + |
| 85 | +当 AI 助理参与代码修改时，在 commit message 末尾添加： |
| 86 | +``` |
| 87 | +Co-Authored-By: GLM-4.7 & cloco(Closer) |
| 88 | +``` |
| 89 | + |
| 90 | +**重要**: 修改代码后不要自动 commit，等待用户查阅同意。 |
| 91 | + |
| 92 | +### 文件读取策略 |
| 93 | + |
| 94 | +**根据文件类型选择工具**: |
| 95 | + |
| 96 | +| 文件类型 | 推荐工具 | 原因 | |
| 97 | +|---------|---------|------| |
| 98 | +| 小文件 (< 10KB) | `readFile` | 读取全部 | |
| 99 | +| 中等文件 (10-100KB) | `readFileLines` | 按行读取 | |
| 100 | +| 大文件 (> 100KB) | `readFileLines` / `readFileChunk` | 分段读取 | |
| 101 | +| Minified JS/CSS | `readFileChunk` | 单行文件，按字节读取 | |
| 102 | +| 日志文件 | `readFileTail` | 从末尾读取 | |
| 103 | + |
| 104 | +**检测超长行**: 文件包含 > 10000 字符的行时，工具会自动警告 |
| 105 | + |
| 106 | +### Bash 输出处理 |
| 107 | + |
| 108 | +**大输出机制**: |
| 109 | +- 输出 > 100 行 → 返回 `result_id` |
| 110 | +- 完整结果缓存 10 分钟 |
| 111 | +- 使用 `bashResult` 工具获取更多内容 |
| 112 | + |
| 113 | +**正确做法**: |
| 114 | +```javascript |
| 115 | +// ❌ 不要重新运行 |
| 116 | +bash({ command: "npm list | head -50" }) |
| 117 | + |
| 118 | +// ✅ 使用 bashResult |
| 119 | +bashResult({ result_id: "res_123", action: "head", lines: 50 }) |
| 120 | +``` |
| 121 | + |
| 122 | +## 开发指导 |
| 123 | + |
| 124 | +### 添加新工具 |
| 125 | + |
| 126 | +在 `src/tools.js` 中定义： |
| 127 | +```javascript |
| 128 | +import { betaZodTool } from '@anthropic-ai/sdk/helpers/beta/zod'; |
| 129 | +import { z } from 'zod'; |
| 130 | + |
| 131 | +export const myTool = betaZodTool({ |
| 132 | + name: 'myTool', |
| 133 | + description: '工具描述', |
| 134 | + inputSchema: z.object({ |
| 135 | + param1: z.string().describe('参数描述') |
| 136 | + }), |
| 137 | + run: async (input) => { |
| 138 | + // 工具逻辑 |
| 139 | + return JSON.stringify({ success: true, data: ... }); |
| 140 | + } |
| 141 | +}); |
| 142 | +``` |
| 143 | + |
| 144 | +添加到 `TOOLS_MAP` 和配置的 `tools.enabled` 数组。 |
| 145 | + |
| 146 | +### 创建新技能 |
| 147 | + |
| 148 | +1. 创建目录: `~/.closer-code/skills/my-skill/` |
| 149 | +2. 创建文件: `SKILL.md` |
| 150 | +3. 格式: |
| 151 | +```markdown |
| 152 | +--- |
| 153 | +name: my-skill |
| 154 | +description: 技能描述 |
| 155 | +category: 分类 |
| 156 | +--- |
| 157 | + |
| 158 | +# 技能内容 |
| 159 | + |
| 160 | +描述技能的能力和使用方法。 |
| 161 | +``` |
| 162 | + |
| 163 | +### 斜杠命令 |
| 164 | + |
| 165 | +在 `src/commands/slash-commands.js` 中添加命令： |
| 166 | +```javascript |
| 167 | +export function myCommand(options = {}) { |
| 168 | + const { markdown = true } = options; |
| 169 | + return { |
| 170 | + success: true, |
| 171 | + content: markdown ? '中文输出' : 'English output' |
| 172 | + }; |
| 173 | +} |
| 174 | +``` |
| 175 | + |
| 176 | +注册到 `COMMAND_REGISTRY`。 |
| 177 | + |
| 178 | +## 配置理解 |
| 179 | + |
| 180 | +**配置优先级**: 项目配置 > 全局配置 > 环境变量 |
| 181 | + |
| 182 | +**关键配置项**: |
| 183 | +- `ai.provider`: AI 提供商 (anthropic/openai/deepseek) |
| 184 | +- `behavior.autoPlan`: 自动任务规划 |
| 185 | +- `behavior.autoExecute`: 自动执行工具 |
| 186 | +- `skills.enabled`: 启用技能系统 |
| 187 | +- `skills.resident`: 常驻技能列表 |
| 188 | +- `mcp.servers`: MCP 服务器配置 |
| 189 | + |
| 190 | +## MCP 集成 |
| 191 | + |
| 192 | +**MCP 工具自动加载**: 启用后，MCP 工具会自动添加到工具列表。 |
| 193 | + |
| 194 | +**配置位置**: `config.json` 的 `mcp.servers` 数组 |
| 195 | + |
| 196 | +## 测试和调试 |
| 197 | + |
| 198 | +**运行测试**: |
| 199 | +```bash |
| 200 | +npm test # 模块测试 |
| 201 | +npm run test:mcp # MCP 测试 |
| 202 | +npm run check # 检查编译 |
| 203 | +``` |
| 204 | + |
| 205 | +**调试技巧**: |
| 206 | +- 使用 `/config` 查看当前配置 |
| 207 | +- 使用 `/skills` 查看技能状态 |
| 208 | +- 使用 `/status` 查看对话摘要 |
| 209 | + |
| 210 | +## 重要提示 |
| 211 | + |
| 212 | +1. **不要破坏功能**: 修改后至少检查编译 (`npm run check`) |
| 213 | +2. **保持简洁**: 代码应该简洁明了，避免过度复杂化 |
| 214 | +3. **类型安全**: 使用 Zod schema 确保类型安全 |
| 215 | +4. **错误友好**: 提供清晰的错误信息和修复建议 |
| 216 | +5. **中文优先**: 注释和文档使用中文 |
| 217 | + |
| 218 | +## 项目信息 |
| 219 | + |
| 220 | +- **仓库**: https://github.com/uppet/closer-code |
| 221 | +- **主入口**: `src/index.js` |
| 222 | +- **CLI 入口**: `src/closer-cli.jsx` |
| 223 | +- **批处理**: `src/batch-cli.js` |
| 224 | +- **Node 版本**: >= 18.0.0 |
| 225 | + |
| 226 | +--- |
| 227 | + |
| 228 | +**核心原则**: 让 AI 助理能够快速理解项目结构，遵循开发规范，高效完成任务。 |
0 commit comments