@unity-china/codely-cli 1.0.0-alpha.1

package/README.zh-CN.md

@@ -0,0 +1,336 @@
+# Codely CLI
+
+<div align="center">
+
+![Codely CLI 截图](https://internal-api-drive-stream.feishu.cn/space/api/box/stream/download/v2/cover/SDRJbcEfUoQRsVxcPJ8ccKTdnMc/?fallback_source=1&height=1280&mount_node_token=JRnkdygOJoQcpyxlCQncsGtMnTc&mount_point=docx_image&policy=equal&width=1280)
+
+[![npm 版本](https://img.shields.io/npm/v/@unity-china/codely-cli.svg)](https://www.npmjs.com/package/@unity-china/codely-cli)
+[![许可证](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](./LICENSE)
+[![Node.js 版本](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
+[![下载量](https://img.shields.io/npm/dm/@unity-china/codely-cli.svg)](https://www.npmjs.com/package/@unity-china/codely-cli)
+
+**面向开发者的 AI 驱动命令行工作流工具**
+
+🌐 [官方网站](https://codely.tuanjie.cn/) • 📖 [使用手册](https://yousandi.feishu.cn/wiki/Sqmlw31sYiTm8qkh7s1cSlbenmb) • 🇺🇸 [English](./README.md)
+
+[安装](#安装) • [快速开始](#快速开始) • [核心功能](#核心功能)
+
+</div>
+
+## 核心功能
+
+- **代码理解与编辑** - 查询和编辑超出传统上下文窗口限制的大型代码库
+- **工作流自动化** - 自动化处理拉取请求和复杂变基等操作任务
+- **AI 智能体系统** - 专业的智能代理，用于深度代码库分析和自动化任务
+- **MCP 集成** - 通过模型上下文协议服务器扩展外部工具和服务能力
+- **Unity 集成** - 与 Unity/团结引擎直接集成，支持游戏开发任务
+- **截图分析** - 分析截图和图像以理解 UI/UX 并提取信息
+- **沙箱环境** - 多种沙箱模式的安全执行环境
+- **IDE 插件** - VS Code 扩展实现无缝集成
+
+## 🤖 AI 智能体系统
+
+Codely CLI 包含强大的智能体系统，提供专业的 AI 助手处理复杂的开发任务：
+
+### 智能体使用
+
+**交互模式**（智能体自动调用）：
+
+```bash
+codely
+> 分析这个 React 项目的组件架构并识别性能瓶颈
+```
+
+**非交互模式**支持不同的输出格式：
+
+```bash
+# 标准文本输出
+codely --prompt "分析 API 端点和安全措施"
+
+# JSON 输出用于自动化
+codely --output-format json --prompt "调查代码库结构" > analysis.json
+
+# 流式 JSON 用于实时监控
+codely --output-format stream-json --prompt "记录数据流" | jq '.type == "agent_think"'
+```
+
+### 智能体管理
+
+**列出可用的智能体：**
+
+```bash
+/agents list
+```
+
+**创建自定义智能体：**
+
+```bash
+# 项目级别智能体
+/agents create security-auditor
+
+# 全局智能体
+/agents create my-helper --global
+
+# 带自定义描述
+/agents create api-analyzer "分析 API 端点和文档"
+```
+
+**智能体位置：**
+
+- **项目智能体**：`.codely-cli/agents/`（与团队共享）
+- **全局智能体**：`~/.codely-cli/agents/`（个人使用）
+
+### 智能体输出示例
+
+智能体提供结构化的完整结果：
+
+**交互式进度：**
+
+```
+🚀 委派给 codebase_investigator 子智能体...
+🔧 [1] 列出目录 - 扫描项目结构
+✅ 列出目录完成 - 找到 45 个目录
+🤖💭 正在分析 package.json 依赖...
+🔧 [2] 读取文件 - package.json
+✅ 读取文件完成 - 分析依赖中
+📋 结果:
+{
+  "SummaryOfFindings": "React 应用采用三层架构...",
+  "ExplorationTrace": ["分析项目结构", "检查路由"],
+  "RelevantLocations": ["src/components/App.tsx", "src/api/routes.ts"]
+}
+```
+
+## 安装
+
+### 前置要求
+
+确保已安装 [Node.js 20](https://nodejs.org/en/download) 或更高版本。
+
+### 直接安装
+
+```bash
+npm i -g @unity-china/codely-cli
+```
+
+## 快速开始
+
+```bash
+# 启动
+codely
+
+# 示例命令
+> 解释这个代码库结构
+> 帮我重构这个函数
+> 为这个模块生成单元测试
+```
+
+### 会话管理
+
+通过可配置的会话限制控制您的 token 使用量，以优化成本和性能。
+
+#### 配置会话 Token 限制
+
+在您的主目录中创建或编辑 `.codely-cli/settings.json`：
+
+```json
+{
+  "sessionTokenLimit": 32000
+}
+```
+
+#### 会话命令
+
+- **`/compress`** - 压缩对话历史以继续在 token 限制内使用
+- **`/clear`** - 清除所有对话历史并重新开始
+- **`/stats`** - 检查当前 token 使用情况和限制
+
+> 📝 **注意**：会话 token 限制适用于单次对话，而非累计 API 调用。
+
+## 使用示例
+
+### 🔍 探索代码库
+
+```bash
+cd your-project/
+codely
+
+# 架构分析
+> 描述这个系统架构的主要部分
+> 关键依赖是什么，它们如何交互？
+> 查找所有 API 端点及其认证方法
+```
+
+### 💻 代码开发
+
+```bash
+# 重构
+> 重构这个函数以提高可读性和性能
+> 将这个类转换为使用依赖注入
+> 将这个大模块拆分成更小、更专注的组件
+
+# 代码生成
+> 创建一个用户管理的 REST API 端点
+> 为认证模块生成单元测试
+> 为所有数据库操作添加错误处理
+```
+
+### 🔄 自动化工作流
+
+```bash
+# Git 自动化
+> 分析过去 7 天的 git 提交，按功能分组
+> 从最近的提交创建变更日志
+> 查找所有 TODO 注释并创建 GitHub issues
+
+# 文件操作
+> 将此目录中的所有图像转换为 PNG 格式
+> 将所有测试文件重命名为 *.test.ts 模式
+> 查找并删除所有 console.log 语句
+```
+
+### 🐛 调试与分析
+
+```bash
+# 性能分析
+> 识别这个 React 组件中的性能瓶颈
+> 在代码库中查找所有 N+1 查询问题
+
+# 安全审计
+> 检查潜在的 SQL 注入漏洞
+> 查找所有硬编码的凭据或 API 密钥
+```
+
+## 常用任务
+
+### 📚 理解新代码库
+
+```text
+> 核心业务逻辑组件是什么？
+> 有哪些安全机制？
+> 数据如何在系统中流动？
+> 使用了哪些主要设计模式？
+> 为这个模块生成依赖关系图
+```
+
+### 🔨 代码重构与优化
+
+```text
+> 这个模块的哪些部分可以优化？
+> 帮我重构这个类以遵循 SOLID 原则
+> 添加适当的错误处理和日志记录
+> 将回调转换为 async/await 模式
+> 为昂贵的操作实现缓存
+```
+
+### 📝 文档与测试
+
+```text
+> 为所有公共 API 生成全面的 JSDoc 注释
+> 编写包含边界情况的单元测试
+> 以 OpenAPI 格式创建 API 文档
+> 添加解释复杂算法的内联注释
+> 为这个模块生成 README
+```
+
+### 🚀 开发加速
+
+```text
+> 设置一个带认证的新 Express 服务器
+> 创建一个带 TypeScript 和测试的 React 组件
+> 实现一个速率限制中间件
+> 为新架构添加数据库迁移
+> 为这个项目配置 CI/CD 流水线
+```
+
+## 命令与快捷键
+
+### 会话命令
+
+- `/help` - 显示可用命令
+- `/clear` - 清除对话历史
+- `/compress` - 压缩历史以节省 tokens
+- `/stats` - 显示当前会话信息
+- `/exit` 或 `/quit` - 退出 Codely CLI
+
+### MCP 命令
+
+管理模型上下文协议（MCP）服务器以扩展 Codely 的外部工具和服务能力：
+
+- `/mcp` - 列出已配置的 MCP 服务器及其可用工具
+- `/mcp desc` - 显示服务器和工具的详细描述
+- `/mcp schema` - 显示工具参数架构
+- `/mcp auth <server-name>` - 对启用 OAuth 的 MCP 服务器进行身份验证
+- `/mcp refresh` - 刷新 MCP 服务器和工具列表
+
+管理 MCP 服务器配置的 CLI 命令：
+
+#### `codely mcp add <name> <commandOrUrl> [args...]`
+
+添加具有指定名称和连接详情的新 MCP 服务器。
+
+**选项：**
+
+- `--scope` (`-s`) - 配置范围（user 或 project）
+- `--transport` (`-t`) - 传输类型（stdio、sse、http）
+- `--env` (`-e`) - 为 stdio 传输设置环境变量（例如 `-e KEY=value`）
+- `--header` (`-H`) - 为 SSE 和 HTTP 传输设置 HTTP 头（例如 `-H "X-Api-Key: abc123"`）
+- `--timeout` - 连接超时时间（毫秒）
+- `--trust` - 信任服务器（绕过所有工具调用确认提示）
+- `--description` - 服务器描述
+- `--include-tools` - 要包含的工具的逗号分隔列表
+- `--exclude-tools` - 要排除的工具的逗号分隔列表
+
+**传输类型：**
+
+- `stdio`（默认）- 使用指定的命令和参数启动进程
+- `sse` - 使用服务器发送事件协议连接到服务器
+- `http` - 使用 HTTP 协议连接到服务器
+
+**示例：**
+
+```bash
+# 添加 stdio 服务器
+codely mcp add my-server python /path/to/server.py --env API_KEY=abc123
+
+# 添加 HTTP 服务器
+codely mcp add my-http-server http://localhost:8000 --transport http --header "Authorization: Bearer token"
+
+# 添加具有范围配置的服务器
+codely mcp add my-server python /path/to/server.py --scope user
+```
+
+#### `codely mcp list`
+
+列出所有已配置的 MCP 服务器及其连接状态。
+
+#### `codely mcp remove <name>`
+
+删除具有指定名称的 MCP 服务器。
+
+**选项：**
+
+- `--scope` (`-s`) - 配置范围（user 或 project）
+
+### 键盘快捷键
+
+- `Ctrl+C` - 取消当前操作
+- `Ctrl+D` - 退出（在空行上）
+- `上/下箭头` - 浏览命令历史
+
+## 故障排除
+
+如果您遇到问题，请检查错误消息并确保：
+
+- Node.js 版本为 20 或更高
+- 所有依赖项已正确安装
+- API 密钥在设置中正确配置
+
+如需更多帮助，请访问：
+
+- 🌐 [官方网站](https://codely.tuanjie.cn/)
+- 📖 [使用手册](https://yousandi.feishu.cn/wiki/Sqmlw31sYiTm8qkh7s1cSlbenmb)
+
+## 许可证
+
+[LICENSE](./LICENSE)

package/bundle/example-prompts/README.md

@@ -0,0 +1,56 @@
+# Example Prompts
+
+This directory contains example prompts that can be used with the CLI. These prompts are bundled with the CLI package for easy access.
+
+## Available Example Prompts
+
+- `git-commit` - Review Git staged changes, generate commit message and commit
+- `analyze` - Analyze an open/complex topic across a very large codebase
+- `explain-code` - Analyze and explain code functionality in detail
+
+## Using Example Prompts
+
+### In Non-Interactive Mode
+
+You can use these example prompts directly in non-interactive mode with the `--example-prompt` flag:
+
+```bash
+# Run the git-commit example
+codely --yolo --example-prompt git-commit
+
+# List all available example prompts
+codely --list-example-prompts
+```
+
+### In Interactive Mode
+
+In interactive mode, you can use the `/example-prompt` slash command:
+
+```bash
+# Start interactive mode
+codely
+
+# Then use the command:
+/example-prompt git-commit
+
+# Or for the explain-code prompt:
+/example-prompt explain-code
+
+# Or list available prompts:
+/example-prompt
+```
+
+## Features
+
+This functionality allows you to:
+
+- Execute pre-defined prompts without needing to type them out
+- Create reusable prompt templates for common tasks
+- Share standardized prompts across your team
+- List all available prompts to see what's available
+
+## Notes
+
+- The `--example-prompt` flag cannot be used together with `--prompt` or `--prompt-interactive`
+- Example prompts must be TOML files with at least a `prompt` field
+- The `description` field is optional but recommended for better documentation

package/bundle/example-prompts/analyze.toml

@@ -0,0 +1,47 @@
+description = "Analyze an open/complex topic across a very large codebase"
+prompt = """
+You are an expert in Unity Game Engine and a large-repo explorer. Your task is to investigate an open/complex topic across a very large Unity/engine-adjacent codebase and produce evidence-backed findings with prioritized recommendations. Provide analysis only; do not modify any code or files.
+
+Analysis Topic: {input}
+
+Topic-driven goals:
+1. **Topic Framing**: Restate the topic; define scope, assumptions, hypotheses, key questions, and success criteria.
+2. **Relevance Mapping**: Identify likely subsystems, languages, directories, services, data models, build/CI pieces, and runtime contexts that relate to the topic.
+3. **Investigation Plan**: Break work into steps using sequential_think and create a plan with job_create; prefer independent steps in parallel; set an IO/search budget per step.
+4. **Evidence Gathering**: Use semantic search first, then narrow with exact matches; read only focused file ranges; capture citations with file paths and line numbers.
+5. **Synthesis**: Connect evidence to findings; quantify impact and risk; propose concrete changes.
+
+Search and tooling rules (MANDATORY):
+- **MUST use sequential_think first** to define scope and create a plan with job_create before any search.
+- **ALWAYS keep searches tightly scoped** to specific directories/files; avoid using project root "./" as the target.
+- Prefer codebase_search for semantic discovery; use grep/glob only for exact symbols/strings within the scoped paths.
+- Use read_file only for specific, bounded ranges; avoid opening entire large files unless necessary.
+- Run independent searches/reads in parallel (limit 3–5 concurrent) to improve throughput.
+- Respect .gitignore; skip vendor, build artifacts, logs, binaries, and large auto-generated files.
+
+Operating constraints (MANDATORY):
+- Analysis-only mode: Do not create/edit/delete files, refactor code, or apply patches.
+- Do not run any state-changing commands; propose commands as suggestions without executing them.
+- Avoid large code dumps or sweeping rewrites; use minimal illustrative snippets only when strictly necessary.
+
+Output format (ADAPTIVE):
+Always include:
+- **Executive Summary (3–7 bullets)**: Key findings, impact, confidence.
+- **Topic Framing**: Scope, assumptions, hypotheses, key questions, success criteria.
+- **Findings & Evidence**: Evidence-backed observations with citations; note trade-offs and confidence.
+- **Key Examples**: Code Fragments, Functions and Classes.
+- **Appendix**: Citations with file paths and line ranges.
+
+Citation requirements:
+- When quoting code, include minimal necessary lines and show file path and line numbers.
+- Keep snippets small; prefer targeted additional reads over large dumps.
+
+Notes:
+- If the topic is ambiguous, briefly state assumptions and proceed; do not stall.
+- Optimize for breadth-first discovery first, then go deep where evidence indicates hotspots.
+- Keep explanations concise but precise; avoid generic claims without evidence.
+
+**CRITICAL**: You MUST NOT use Grep/Glob tool under project root "./". You MUST use sequential_thining to narrow down the search scope to folder.
+
+Focus on providing constructive, actionable feedback suitable for large-scale codebases.
+"""

package/bundle/example-prompts/explain-code.toml

@@ -0,0 +1,200 @@
+description = "Analyze and explain code functionality in detail"
+prompt = """
+You are an expert software engineer and code analyst. Your task is to analyze and explain the functionality of the provided code in detail. Provide a comprehensive analysis only; do not modify any code or files.
+
+Code to analyze: {input}
+
+Follow this systematic approach to explain the code:
+
+1. **Code Context Analysis**
+   - Identify the programming language and framework
+   - Understand the broader context and purpose of the code
+   - Identify the file location and its role in the project
+   - Review related imports, dependencies, and configurations
+
+2. **High-Level Overview**
+   - Provide a summary of what the code does
+   - Explain the main purpose and functionality
+   - Identify the problem the code is solving
+   - Describe how it fits into the larger system
+
+3. **Code Structure Breakdown**
+   - Break down the code into logical sections
+   - Identify classes, functions, and methods
+   - Explain the overall architecture and design patterns
+   - Map out data flow and control flow
+
+4. **Line-by-Line Analysis**
+   - Explain complex or non-obvious lines of code
+   - Describe variable declarations and their purposes
+   - Explain function calls and their parameters
+   - Clarify conditional logic and loops
+
+5. **Algorithm and Logic Explanation**
+   - Describe the algorithm or approach being used
+   - Explain the logic behind complex calculations
+   - Break down nested conditions and loops
+   - Clarify recursive or asynchronous operations
+
+6. **Data Structures and Types**
+   - Explain data types and structures being used
+   - Describe how data is transformed or processed
+   - Explain object relationships and hierarchies
+   - Clarify input and output formats
+
+7. **Framework and Library Usage**
+   - Explain framework-specific patterns and conventions
+   - Describe library functions and their purposes
+   - Explain API calls and their expected responses
+   - Clarify configuration and setup code
+
+8. **Error Handling and Edge Cases**
+   - Explain error handling mechanisms
+   - Describe exception handling and recovery
+   - Identify edge cases being handled
+   - Explain validation and defensive programming
+
+9. **Performance Considerations**
+   - Identify performance-critical sections
+   - Explain optimization techniques being used
+   - Describe complexity and scalability implications
+   - Point out potential bottlenecks or inefficiencies
+
+10. **Security Implications**
+    - Identify security-related code sections
+    - Explain authentication and authorization logic
+    - Describe input validation and sanitization
+    - Point out potential security vulnerabilities
+
+11. **Testing and Debugging**
+    - Explain how the code can be tested
+    - Identify debugging points and logging
+    - Describe mock data or test scenarios
+    - Explain test helpers and utilities
+
+12. **Dependencies and Integrations**
+    - Explain external service integrations
+    - Describe database operations and queries
+    - Explain API interactions and protocols
+    - Clarify third-party library usage
+
+**Explanation Format Examples:**
+
+**For Complex Algorithms:**
+```
+This function implements a depth-first search algorithm:
+
+1. Line 1-3: Initialize a stack with the starting node and a visited set
+2. Line 4-8: Main loop - continue until stack is empty
+3. Line 9-11: Pop a node and check if it's the target
+4. Line 12-15: Add unvisited neighbors to the stack
+5. Line 16: Return null if target not found
+
+Time Complexity: O(V + E) where V is vertices and E is edges
+Space Complexity: O(V) for the visited set and stack
+```
+
+**For API Integration Code:**
+```
+This code handles user authentication with a third-party service:
+
+1. Extract credentials from request headers
+2. Validate credential format and required fields
+3. Make API call to authentication service
+4. Handle response and extract user data
+5. Create session token and set cookies
+6. Return user profile or error response
+
+Error Handling: Catches network errors, invalid credentials, and service unavailability
+Security: Uses HTTPS, validates inputs, and sanitizes responses
+```
+
+**For Database Operations:**
+```
+This function performs a complex database query with joins:
+
+1. Build base query with primary table
+2. Add LEFT JOIN for related user data
+3. Apply WHERE conditions for filtering
+4. Add ORDER BY for consistent sorting
+5. Implement pagination with LIMIT/OFFSET
+6. Execute query and handle potential errors
+7. Transform raw results into domain objects
+
+Performance Notes: Uses indexes on filtered columns, implements connection pooling
+```
+
+13. **Common Patterns and Idioms**
+    - Identify language-specific patterns and idioms
+    - Explain design patterns being implemented
+    - Describe architectural patterns in use
+    - Clarify naming conventions and code style
+
+14. **Potential Improvements**
+    - Suggest code improvements and optimizations
+    - Identify possible refactoring opportunities
+    - Point out maintainability concerns
+    - Recommend best practices and standards
+
+15. **Related Code and Context**
+    - Reference related functions and classes
+    - Explain how this code interacts with other components
+    - Describe the calling context and usage patterns
+    - Point to relevant documentation and resources
+
+16. **Debugging and Troubleshooting**
+    - Explain how to debug issues in this code
+    - Identify common failure points
+    - Describe logging and monitoring approaches
+    - Suggest testing strategies
+
+**Language-Specific Considerations:**
+
+**JavaScript/TypeScript:**
+- Explain async/await and Promise handling
+- Describe closure and scope behavior
+- Clarify this binding and arrow functions
+- Explain event handling and callbacks
+
+**Python:**
+- Explain list comprehensions and generators
+- Describe decorator usage and purpose
+- Clarify context managers and with statements
+- Explain class inheritance and method resolution
+
+**Java:**
+- Explain generics and type parameters
+- Describe annotation usage and processing
+- Clarify stream operations and lambda expressions
+- Explain exception hierarchy and handling
+
+**C#:**
+- Explain LINQ queries and expressions
+- Describe async/await and Task handling
+- Clarify delegate and event usage
+- Explain nullable reference types
+
+**Go:**
+- Explain goroutines and channel usage
+- Describe interface implementation
+- Clarify error handling patterns
+- Explain package structure and imports
+
+**Rust:**
+- Explain ownership and borrowing
+- Describe lifetime annotations
+- Clarify pattern matching and Option/Result types
+- Explain trait implementations
+
+Remember to:
+- Use clear, non-technical language when possible
+- Provide examples and analogies for complex concepts
+- Structure explanations logically from high-level to detailed
+- Include visual diagrams or flowcharts when helpful
+- Tailor the explanation level to the intended audience
+
+Operating constraints (MANDATORY):
+- Analysis-only mode: Do not create/edit/delete files, refactor code, or apply patches.
+- Do not run any state-changing commands; propose commands as suggestions without executing them.
+- Avoid large code dumps or sweeping rewrites; use minimal illustrative snippets only when strictly necessary.
+"""

package/bundle/example-prompts/git-commit.toml

@@ -0,0 +1,48 @@
+description = "Review Git staged changes, generate commit message and commit"
+prompt = """
+You are a professional Git user assistant. Your task is to help users complete the following operations:
+1. Review current Git staged changes
+2. Generate appropriate commit messages based on the changes
+3. Execute git commit command to commit the changes
+
+Please follow these steps:
+1. First run `git diff --cached` command to view the staged changes
+2. Analyze these changes to understand the content and purpose of modifications
+3. Generate a clear, concise and conventional commit message based on the changes
+   - Must use English and keep commit messages consistency
+   - Follow conventional commits specification (use prefixes like feat:, fix:, docs:, style:, refactor:, perf:, test:, chore:, etc.)
+   - Structure:
+     * First line: concise title with conventional commit prefix. Title length MUST be less than 50
+     * Second line: blank line (required)
+     * Body paragraph: a descriptive paragraph (within 200 words) explaining the target of the commit - what feature is being added or what problem is being fixed. This should provide context and motivation for the changes.
+     * Third line: blank line (required)
+     * Bullet points: use bullet points (with '-' prefix) to list main changes
+     * Each bullet point should be concise and focused on one specific change
+     * Group related changes together logically
+     * Keep each bullet point to one line when possible
+   - Example format:
+     ```
+     feat: enhance compress command and update system prompt
+
+     This commit improves the compress command functionality to provide better user experience and feedback. The main goal is to enhance logging capabilities, display detailed compression statistics, and improve test coverage. Additionally, it updates the system prompt to reflect the rebranding of the agent to 'Codely CLI', ensuring consistency across the codebase.
+
+     - Improve compress command with better logging and user feedback
+     - Add detailed compression ratio information and summary display
+     - Enhance test coverage with console spies and assertions
+     - Update system prompt to rename agent to 'Codely CLI'
+     ```
+4. Show the generated commit message to the user
+5. IMPORTANT: Execute the commit using `git commit -m "commit_message"` command
+   - Must use the ShellTool to execute the git commit command
+   - Always use the `-m` flag with the message in double quotes
+   - For multiline commit messages, MUST use multiple `-m` flags to specify each line
+   - Example: `git commit -m "feat: add feature" -m "This commit adds a new feature to improve..." -m "- Change A" -m "- Change B"`
+   - The system will automatically handle any additional metadata
+   - If precommit hook failed, we MUST stop commit. We SHOULD NOT fix them.
+6. Report the commit result to the user or report errors and stop
+
+Please note:
+- If there are no staged changes, remind the user to first use `git add` to add changes to the staging area
+- Keep interactions friendly and ensure the user understands each step of the operation
+"""
+