Add executor module local development documentation #108
Conversation
This documentation provides comprehensive guidance for developers to set up and run the executor module locally using uv package manager. Key sections include: - Project structure overview - Environment setup with uv - Required and optional environment variables - Step-by-step startup instructions - API endpoint documentation - Quick start script examples - Development debugging tips - Common troubleshooting solutions
|
Warning Rate limit exceeded@Micro66 has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 15 minutes and 58 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
WalkthroughAdds a new local development documentation file for the Executor module covering project overview, structure, environment setup, dependency installation, service startup, API endpoints, quick-start examples, debugging, tests, troubleshooting, and future work references. Changes
Sequence Diagram(s)(No sequence diagram included — changes are documentation-only and do not modify runtime control flow.) Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
executor/LOCAL_DEV.md (3)
9-24: Specify language identifier for fenced code block.The directory tree code block lacks a language specification. Add an appropriate identifier after the opening backticks or use plain text formatting.
-``` +```text executor/ ├── agents/ # Agent 实现
117-127: Clarify service verification endpoint.The comment states "检查服务健康状态" (check service health status), but the curl command targets
/docs, which is the API documentation endpoint. This verifies the service is running but is not a dedicated health check endpoint. Either clarify the intent or add a dedicated health endpoint check if one exists.Consider adding a dedicated health check:
# 检查服务健康状态 -curl http://localhost:10001/docs +curl http://localhost:10001/health # 查看 API 文档Alternatively, clarify the verification comment to reflect what the /docs endpoint actually checks.
57-90: Add security guidance for credentials handling.While the documentation uses placeholder values (e.g.,
your-anthropic-api-key) appropriately, it lacks explicit guidance on secure credential management for local development. Developers should be warned against hardcoding credentials in scripts or committing them to version control.Consider adding a security note:
### 步骤 2: 配置环境变量 Executor 需要以下环境变量进行配置： + +> **⚠️ 安全提示：** 切勿将 API 密钥硬编码在脚本或代码中。建议使用 `.env` 文件并将其添加到 `.gitignore`，或使用密钥管理服务。 #### 必需环境变量
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
executor/LOCAL_DEV.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
executor/LOCAL_DEV.md
9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
Enhanced the local development documentation to properly guide developers in using uv virtual environments for dependency isolation. Key improvements: - Added step-by-step virtual environment creation and activation - Reorganized steps to prioritize venv setup before dependency installation - Updated quick start script to include automatic venv creation and activation - Added important note about virtual environment benefits - Enhanced startup instructions with multiple execution methods - Included troubleshooting for venv-related issues - Added new FAQ entries for venv activation and uv installation This ensures developers follow best practices by running all commands within an isolated virtual environment.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
executor/LOCAL_DEV.md (4)
9-24: Specify language for the project structure code block.The code block documenting the project structure should have a language specified for proper markdown rendering. Since this is a tree structure (not code), use the
textlanguage identifier.-``` +```text executor/Based on static analysis hint from markdownlint.
47-64: Expand Windows setup instructions for virtual environment.Virtual environment activation for Windows is mentioned but only in a comment (line 63). Provide consistent full instructions for Windows users to ensure parity with Linux/macOS documentation.
# 激活虚拟环境 # Linux/macOS: source .venv/bin/activate -# Windows: -# .venv\Scripts\activate +# Windows: +.venv\Scripts\activateThis change makes Windows instructions equally prominent and actionable.
203-246: Quick start script is well-structured.The shell script provides a complete setup flow with good defensive programming (checking for existing venv). The example is clear and consistent with earlier documentation. One suggestion: consider adding error handling with
set -eto exit on command failures.#!/bin/bash +set -e # Exit on first error # 设置环境变量This ensures the script stops if any command fails, improving reliability during setup.
155-201: API endpoints verified—documentation is accurate but could include more detail for consistency.All five documented endpoints are correctly implemented in
executor/main.py. For improved consistency and developer experience, consider adding request/response examples and parameter descriptions for endpoints 2–5 to match the detail level of the execute endpoint (e.g., response formats, status codes for DELETE operations, query parameter descriptions fordelete_session).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
executor/LOCAL_DEV.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
executor/LOCAL_DEV.md
9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (6)
executor/LOCAL_DEV.md (6)
265-290: VS Code debug configuration looks correct.The launch configuration uses standard patterns for Python debugging with uvicorn. The JSON structure appears valid, and environment variable setup is appropriate. Verify this configuration works with the VS Code Python extension in your development environment.
To verify the configuration works:
- Copy the launch.json configuration into
.vscode/launch.json- Set a breakpoint in the executor code
- Press F5 to start debugging
- Verify breakpoints are hit and the debugger responds correctly
292-316: Test documentation is comprehensive and well-structured.The test execution section appropriately covers installation of test dependencies, multiple execution methods, and coverage generation. The examples are practical and consistent with pytest conventions.
318-385: Troubleshooting section is practical and well-targeted.The five common issues cover the most likely setup problems a developer would encounter. Each issue includes realistic error messages, clear explanations, and actionable solutions. This section effectively de-risks the developer onboarding process.
1-8: Document overview is clear and well-positioned.The title, overview, and project structure introduction effectively set context for developers. The bilingual approach (Chinese/English) is appropriate for an international team.
387-396: Next steps and license sections are appropriate.The "下一步" (Next Steps) section appropriately marks future documentation as "待完成" (to be completed), setting clear expectations. The license reference is standard and correct.
117-135: Module path and FastAPI app reference verified—documentation is accurate.The verification confirms all startup command references are correct:
executor/__init__.pyexists, making executor a proper Python packageexecutor/main.pydefinesapp = FastAPI(...), confirming the app variable is a FastAPI instance- The module paths
executor.main:appandpython -m executor.mainare correctly resolvableNo issues found.
…PATH Critical fixes for local development setup: 1. **Project root directory requirement**: - All operations must be run from project root (Wegent/), not executor subdirectory - Updated all path references and commands to reflect this requirement - Added prominent warning at the beginning of setup instructions 2. **PYTHONPATH configuration**: - Added mandatory PYTHONPATH setup: `export PYTHONPATH=$(pwd)` - Included in all startup instructions and quick start script - Added to troubleshooting section with specific error examples 3. **Updated quick start script**: - Changed from executor/ directory to project root - Auto-detects script location and navigates to project root - Sets PYTHONPATH before starting service - Corrected dependency installation path to executor/requirements.txt 4. **Enhanced troubleshooting**: - Added FAQ for PYTHONPATH not set (FAQ #5) - Added FAQ for running in wrong directory (FAQ #6) - Updated virtual environment FAQ with correct paths 5. **Improved clarity**: - Added warning boxes highlighting critical requirements - Updated all code examples to show correct directory context - Emphasized PYTHONPATH requirement throughout documentation These changes address module import errors that occur when PYTHONPATH is not properly configured or when running from the wrong directory.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
executor/LOCAL_DEV.md (3)
9-24: Add language identifier to project structure code block.The fenced code block showing the project structure is missing a language identifier. Although it displays correctly as a tree structure, adding a language identifier (or marking it as
text) improves markdown consistency and tooling support.-``` +```text executor/ ├── agents/ # Agent 实现
222-263: Script assumes all prerequisites are installed (uv, Python).The quick start script (
start.sh) is well-structured but assumes thatuvis already installed. Consider adding a check or note that ifuvis not found, users should install it first using the instructions provided earlier in the documentation. The script would benefit from better error handling.# 创建虚拟环境（如果不存在） if [ ! -d ".venv" ]; then echo "Creating virtual environment..." + if ! command -v uv &> /dev/null; then + echo "Error: uv is not installed. Please install uv first using:" + echo " curl -LsSf https://astral.sh/uv/install.sh | sh" + exit 1 + fi uv venv fi
446-451: Roadmap links reference non-existent files.The future documentation references (AGENT_DEV.md, CONFIG.md, DEPLOYMENT.md, API.md) are marked as "(待完成)" (to be completed), but the markdown links will currently lead to 404 errors. Consider either:
- Removing the markdown link syntax until files are created
- Using
<!-- TODO: Link when created -->comments instead- Creating placeholder files with "Coming soon" notices
-## 下一步 +## 下一步（参考文档） -- [Agent 开发指南](./AGENT_DEV.md)（待完成） -- [配置详解](./CONFIG.md)（待完成） -- [部署指南](./DEPLOYMENT.md)（待完成） -- [API 参考文档](./API.md)（待完成） +- Agent 开发指南 (AGENT_DEV.md) - 待完成 +- 配置详解 (CONFIG.md) - 待完成 +- 部署指南 (DEPLOYMENT.md) - 待完成 +- API 参考文档 (API.md) - 待完成
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
executor/LOCAL_DEV.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
executor/LOCAL_DEV.md
9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (4)
executor/LOCAL_DEV.md (4)
344-428: Troubleshooting section is comprehensive and well-organized.The troubleshooting section effectively addresses the most common setup issues developers will encounter. The emphasis on project root directory (issue #6) and PYTHONPATH (issue #5) throughout the documentation, combined with detailed troubleshooting steps, should significantly reduce support burden.
318-342: Clarify whether test dependencies are required or optional for the executor module.Pytest and pytest-asyncio are not in
executor/requirements.txt. The documentation instructs users to install them separately viauv pip install pytest pytest-asyncio, but provides no context on whether these are:
- Required for the executor module (should be added to requirements.txt), or
- Optional development-only dependencies (should be documented in a separate dev requirements file or marked as such in this guide)
Recommend either adding test dependencies to the requirements file or explicitly documenting them as optional dev-only setup in the testing section.
83-126: Documentation is accurate; consider adding optional advanced configuration variables.All documented environment variables are correctly recognized by the executor with matching defaults (PORT=10001, WORKSPACE_ROOT=/workspace/, etc.). However, verification reveals several additional optional environment variables available for advanced configuration that are not documented:
REPO_PROXY_CONFIG— proxy routing for repository accessANTHROPIC_BASE_URL,OPENAI_BASE_URL— custom API endpointsANTHROPIC_MODEL,OPENAI_MODEL— override default model IDsCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC,CLAUDE_CODE_INCLUDE_CO_AUTHORED_BY— Claude Code feature flagsDEFAULT_HEADERS— custom headers for requestsConsider adding these to an "Advanced Configuration" section if they are intended for developer use.
128-154: All executor startup methods are valid and properly implemented.Verification confirms that
executor/main.pycontains:
app = FastAPI()as the correct uvicorn entry pointif __name__ == "__main__":block withuvicorn.run()for module executionAll documented startup approaches are valid:
uv run python -m executor.main✓uv run uvicorn executor.main:app --host 0.0.0.0 --port 10001 --reload✓python -m executor.main(in activated venv) ✓uvicorn executor.main:app --host 0.0.0.0 --port 10001 --reload(in activated venv) ✓The PYTHONPATH configuration and project root requirement are correctly documented and necessary for import resolution.
executor/LOCAL_DEV.md
Outdated
| ## API 接口 | ||
|
|
||
| Executor 提供以下主要 API 接口： | ||
|
|
||
| ### 1. 执行任务 | ||
|
|
||
| ```bash | ||
| POST /api/tasks/execute | ||
| Content-Type: application/json | ||
|
|
||
| { | ||
| "task_id": 1, | ||
| "subtask_id": 1, | ||
| "agent_type": "claude_code", | ||
| "task_title": "任务标题", | ||
| "subtask_title": "子任务标题", | ||
| "content": "任务内容", | ||
| "repo_url": "https://github.com/example/repo.git", | ||
| "branch": "main", | ||
| "git_username": "user", | ||
| "git_password": "password" | ||
| } | ||
| ``` | ||
|
|
||
| ### 2. 列出所有会话 | ||
|
|
||
| ```bash | ||
| GET /api/tasks/sessions | ||
| ``` | ||
|
|
||
| ### 3. 删除指定会话 | ||
|
|
||
| ```bash | ||
| DELETE /api/tasks/session?task_id=1 | ||
| ``` | ||
|
|
||
| ### 4. 关闭所有 Claude 会话 | ||
|
|
||
| ```bash | ||
| DELETE /api/tasks/claude/sessions | ||
| ``` | ||
|
|
||
| ### 5. 关闭所有 Agent 会话 | ||
|
|
||
| ```bash | ||
| DELETE /api/tasks/sessions/close | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
Verify API endpoints exist and match implementation.
The documentation lists five API endpoints. Confirm that all endpoints exist, paths are correct, HTTP methods are accurate, and the request payload for /api/tasks/execute includes all required/optional fields. Consider adding response format examples to improve developer experience.
🏁 Script executed:
#!/bin/bash
# Description: Search for API endpoint definitions in executor module.
# Search for FastAPI route definitions
rg -n '@app\.(get|post|delete|put|patch)' executor/ --type py -A 2
# Search for task-related endpoints
rg -n 'api/tasks' executor/ --type py -B 2 -A 5Length of output: 2684
Let me verify the request payload structure for the POST endpoint:
Let me check the actual implementation of the execute_task function to verify what fields are expected:
[/run_scripts]
Based on the verification of the API endpoints, all five endpoints documented in LOCAL_DEV.md match the actual implementation in executor/main.py with correct HTTP methods and paths. The endpoints are:
- ✓ POST /api/tasks/execute
- ✓ GET /api/tasks/sessions
- ✓ DELETE /api/tasks/session (with task_id query parameter)
- ✓ DELETE /api/tasks/claude/sessions
- ✓ DELETE /api/tasks/sessions/close
All API endpoints in the documentation are correct and exist in the implementation with matching paths and HTTP methods.
[resolve_review_comment]
🏁 Script executed:
#!/bin/bash
# Search for execute_task function implementation and how it parses request body
# Get the full execute_task function
rg -n 'async def execute_task' executor/main.py -A 30
# Also look for any request models or schemas
rg -n 'class.*Request\|class.*Task.*Model' executor/ --type pyLength of output: 1075
[/run_scripts]
🏁 Script executed:
#!/bin/bash
# Search for process function and TaskResponse model definition
# Find process function
rg -n 'def process\(' executor/ --type py -A 20
# Find TaskResponse model
rg -n 'class TaskResponse' executor/ --type py -A 15
# Also check imports at top of main.py to understand what models are used
head -50 executor/main.pyLength of output: 3554
[/run_scripts]
🏁 Script executed:
#!/bin/bash
# Find _get_callback_params function to see which fields are used
rg -n '_get_callback_params' executor/ --type py -B 2 -A 15
# Also search for where task fields are used in the process/execution flow
rg -n 'agent_type\|task_title\|content\|repo_url' executor/ --type py -B 2 -A 2Length of output: 2475
[/run_scripts]
🏁 Script executed:
#!/bin/bash
# Find AgentService.execute_task implementation
rg -n 'def execute_task' executor/services/ --type py -A 25
# Also search for actual usage of documented fields throughout the codebase
rg -n 'task_data\[.*agent_type\|task_data\[.*content\|task_data\[.*repo_url\|task_data\[.*branch\|task_data\[.*git_' executor/ --type py -C 2Length of output: 2360
[/run_scripts]
🏁 Script executed:
#!/bin/bash
# Find create_agent method
rg -n 'def create_agent' executor/services/ --type py -A 30
# Also look for how agent_type is used
rg -n 'agent_type' executor/ --type py -B 2 -A 2Length of output: 5865
[/run_scripts]
🏁 Script executed:
#!/bin/bash
# Search for bot configuration examples
rg -n '"bot"\|bot_config' executor/ --type py -B 2 -A 5
# Search for usage of content, repo_url, branch fields
rg -n 'content\|repo_url\|branch\|git_' executor/ --type py -B 1 -A 1 | head -50Length of output: 0
[/run_scripts]
🏁 Script executed:
#!/bin/bash
# Search for test files with example task data
find executor/tests -name "*.py" -type f
# Look for fixture files or conftest
cat executor/tests/conftest.py 2>/dev/null || echo "No conftest"
# Search for example payloads in test files
rg -l "task_id\|subtask_id" executor/tests --type pyLength of output: 2082
[/run_scripts]
🏁 Script executed:
#!/bin/bash
# Search test files for task_data examples
rg -n 'task_data\s*=' executor/tests/ --type py -A 8 | head -80
# Also check for bot configuration in tests
rg -n '"bot"' executor/tests/ --type py -B 2 -A 8Length of output: 811
[/run_scripts]
🏁 Script executed:
#!/bin/bash
# Final verification: search for documented field usage in actual implementation
# Search for task_title, subtask_title usage in actual code (not tests)
rg -n 'task_title\|subtask_title' executor/ --type py -g '!*/tests/*' -B 1 -A 1
# Search for content field usage
rg -n 'task_data.*content\|\.get\("content' executor/ --type py -g '!*/tests/*' -B 1 -A 1
# Search for repo_url or branch or git_ fields
rg -n 'repo_url\|"branch"\|git_username\|git_password' executor/ --type py -g '!*/tests/*' -B 1 -A 1Length of output: 0
Update API request payload documentation - current example is incorrect.
The POST /api/tasks/execute endpoint request payload example in the documentation is incorrect. The documented payload shows "agent_type": "claude_code", but the actual implementation requires a "bot" field with API configuration. Additionally, documented fields like content, repo_url, branch, git_username, and git_password are not used by the executor implementation.
The correct request payload structure should reflect:
"bot": array of objects containing"api_key"and"model"(not"agent_type")"task_id","subtask_id": task identifiers"task_title","subtask_title": used for callbacks"env": optional environment configuration
Remove or clarify the unused fields from the documented example.
Key changes: 1. Translated entire documentation from Chinese to English 2. Fixed CALLBACK_URL path from /api/callback to /executor-manager/callback 3. Maintained all technical accuracy and structure Documentation improvements: - Clear English terminology for international developers - Corrected callback endpoint to match actual service architecture - All code examples, commands, and configurations remain unchanged - Preserved all critical warnings and important notes - Updated section headings, descriptions, and troubleshooting guides This ensures the documentation is accessible to a wider audience while maintaining technical precision.
Summary
This PR adds comprehensive local development documentation for the executor module, focusing on local startup using the uv package manager.
Changes
executor/LOCAL_DEV.mdwith detailed setup instructionsDocumentation Highlights
Covered Topics
Quick Start Guide
The documentation provides clear instructions for:
uv pip install -r requirements.txtuv run uvicorn executor.main:appTarget Audience
This documentation is designed for developers who need to:
Test Plan
Additional Notes
This is the first part of the local development documentation series. Future additions may include:
Summary by CodeRabbit