feat(skill): refactor code execution API with builder pattern

[fang-tech]

AgentScope-Java Version

1.0.7

Description

• Replace enableCodeExecution() with fluent builder API
• Support selective tool enabling and ShellCommandTool customization
• Add cross-platform tests (Unix/Mac + Windows)
• Update documentation with new API examples

BREAKING CHANGE: enableCodeExecution() methods removed, use codeExecution().enable() instead

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[gemini-code-assist]

Summary of Changes

Hello @fang-tech, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the code execution capabilities within the SkillBox by introducing a builder pattern for its API. This refactoring provides greater control and flexibility, allowing developers to precisely configure which code execution tools (shell, read, write) are enabled and to customize the ShellCommandTool with specific security policies and working directories. The change aims to improve the modularity, security, and usability of skill-based code execution within the system.

Highlights

• Refactored Code Execution API: The enableCodeExecution() methods have been replaced with a new fluent builder API, codeExecution(), providing a more flexible and configurable way to enable code execution capabilities for skills.
• Selective Tool Enabling: The new builder pattern allows for selective enabling of code execution tools, such as shell command execution, file reading, and file writing, rather than enabling all by default.
• Customizable ShellCommandTool: Users can now provide a custom ShellCommandTool instance to the builder, allowing for tailored security policies, allowed commands, and approval callbacks, while ensuring the working directory is consistently enforced.
• Enhanced Test Coverage: New and updated tests cover the builder's functionality, including selective tool enabling, custom ShellCommandTool cloning, and cross-platform base directory enforcement for shell commands.
• Documentation Updates: The English and Chinese documentation for agent skills has been updated to reflect the new code execution API, including usage examples and core features.
• Breaking Change: The previous enableCodeExecution() methods have been removed. Users must now use the codeExecution().enable() builder pattern.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant improvement by refactoring the code execution API to use a fluent builder pattern. This change enhances flexibility, allowing for selective tool enabling and custom configurations, which is a great step forward. The code is well-structured, and the accompanying tests are thorough, covering various new scenarios including cross-platform behavior. The documentation has also been updated to reflect these changes. I've identified a potential security inconsistency regarding the sandboxing behavior of the configured tools and a couple of minor areas for improvement in code comments and documentation for better clarity and maintainability.

[Copilot]

Pull request overview

This PR refactors the code execution API from simple method calls to a fluent builder pattern, providing more flexibility for configuring code execution capabilities.

Changes:

• Replaced enableCodeExecution() methods with a fluent builder API accessible via codeExecution()
• Added three new getter methods to ShellCommandTool (getApprovalCallback(), getCommandValidator(), getBaseDir()) to support cloning with workDir override
• Introduced comprehensive cross-platform tests for base directory enforcement and getter methods
• Updated documentation with new API examples in both English and Chinese

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java	Replaced enableCodeExecution methods with CodeExecutionBuilder nested class implementing fluent builder pattern with selective tool enabling
agentscope-core/src/main/java/io/agentscope/core/tool/coding/ShellCommandTool.java	Added three getter methods to enable tool configuration inspection and cloning
agentscope-core/src/test/java/io/agentscope/core/skill/SkillBoxTest.java	Updated all tests to use new builder API and added comprehensive tests for builder features including replacement, selective enabling, and custom tool cloning
agentscope-core/src/test/java/io/agentscope/core/tool/coding/ShellCommandToolTest.java	Added new test suites for getter methods and cross-platform base directory enforcement
docs/zh/task/agent-skill.md	Added Feature 2 section documenting code execution capabilities with builder pattern examples
docs/en/task/agent-skill.md	Added Feature 2 section documenting code execution capabilities with builder pattern examples

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 98.64865% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...c/main/java/io/agentscope/core/skill/SkillBox.java	98.59%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!