Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions .claude/context-summary-工具描述中文化.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
## 项目上下文摘要(工具描述中文化)
生成时间:2026-04-28

### 1. 相似实现分析
- **实现1**: data-agent-management/src/main/java/com/alibaba/cloud/ai/dataagent/agentscope/tool/datasource/DatasourceExplorerToolProvider.java:131-152
- 模式:由 provider 动态构造 `ToolDefinition.description`
- 可复用:中文分点式说明风格,明确适用范围、顺序和禁用场景
- 需注意:描述会直接影响 Agent 工具选择与调用顺序

- **实现2**: data-agent-management/src/main/java/com/alibaba/cloud/ai/dataagent/agentscope/tool/semantic/SemanticModelToolSupport.java:32-50
- 模式:`INPUT_SCHEMA` 采用中文字段说明,强调“必填/可选/何时不必传”
- 可复用:schema 文案风格可直接作为其他工具输入说明参考
- 需注意:和 provider 的 description 要保持边界一致

- **实现3**: data-agent-management/src/main/java/com/alibaba/cloud/ai/dataagent/agentscope/tool/knowledge/DomainBusinessKnowledgeToolSupport.java:37-63
- 模式:support 负责统一 `ToolDefinition` 的 input schema
- 可复用:中文化时优先改 provider 的 DESCRIPTION,support 仅修正残留英文术语
- 需注意:不要改动工具行为,只改面向 Agent 的说明文本

### 2. 项目约定
- **命名约定**: Java 类、常量、方法名保持现有英文命名;说明文本统一简体中文
- **文件组织**: provider 负责工具注册与 description;support 负责 input schema 和 callback 封装
- **导入顺序**: 保持现有 import 顺序,不做无关调整
- **代码风格**: 使用 Java 文本块 `"""` 保存多行描述,延续现有缩进和换行风格

### 3. 可复用组件清单
- `data-agent-management/src/main/java/com/alibaba/cloud/ai/dataagent/agentscope/tool/datasource/DatasourceExplorerToolProvider.java`:中文工具描述样板
- `data-agent-management/src/main/resources/prompts/commonagent.md`:工具边界和调用顺序的权威规则
- `data-agent-management/src/main/java/com/alibaba/cloud/ai/dataagent/agentscope/tool/semantic/SemanticModelToolSupport.java`:中文 schema 样板
- `data-agent-management/src/main/java/com/alibaba/cloud/ai/dataagent/agentscope/tool/knowledge/DomainBusinessKnowledgeToolSupport.java`:中文 schema 样板

### 4. 测试策略
- **测试框架**: 本次先做静态验证,不新增测试
- **验证方式**: 搜索所有注册工具 description / input schema,确认英文描述已清理且工具边界与 `commonagent.md` 一致
- **参考文件**: `commonagent.md`、各 ToolProvider / ToolSupport
- **覆盖要求**: 至少覆盖 `sql_guard.check`、`semantic_model.search`、`domain_business_knowledge.search` 以及已存在中文样板的对齐检查

### 5. 依赖和集成点
- **外部依赖**: Spring AI `ToolDefinition`
- **内部依赖**: `AgentScopedToolProvider`、各 `ToolSupport`
- **集成方式**: provider 将 description 和 inputSchema 注入 `ToolDefinition.builder()`
- **配置来源**: `data-agent-management/src/main/resources/prompts/commonagent.md` 定义工具路由规则

### 6. 技术选型理由
- **为什么用这个方案**: 直接修改 provider/support 文案即可完成目标,影响面准确且不改变运行逻辑
- **优势**: 风险低、改动集中、与现有工具注册结构一致
- **劣势和风险**: 只改文案不跑行为测试;需确保中文说明与现有路由规则完全一致,避免误导模型

### 7. 关键风险点
- **边界条件**: `sql_guard.check` 同时支持 `SQL_VERIFY` 与 `DATA_PROFILE`,描述必须避免把 profile 说成默认步骤
- **一致性风险**: provider description、schema description、`commonagent.md` 三处边界不能冲突
- **维护风险**: 若遗漏某个注册工具,前后端展示和模型行为提示会出现中英混杂
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -65,3 +65,4 @@ data-agent-management/vectorstore/*
# spring-ai-alibaba source
spring-ai-alibaba-1.1.0.0/
.spec-workflow
.claude
2 changes: 1 addition & 1 deletion agent-skills/builtin-domain-business-knowledge/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ description: 当用户问题依赖公司内部业务规则、指标口径、SOP

工作原则:
1. 不要在每一轮都调用工具。只有当回答明显依赖业务知识,或者你不确定业务口径时,才调用 `domain_business_knowledge.search`。
2. 默认优先检索 `businessTerm` 与 `agentKnowledge`。如果你明确知道要查 FAQ、QA 或文档,可以通过 `knowledgeTypes` 缩小范围。
2. 默认优先检索 `businessKnowledge` 与 `agentKnowledge`。如果你明确知道要查 FAQ、QA 或文档,可以通过 `knowledgeTypes` 缩小范围。
3. 将工具返回结果作为“证据”来辅助推理,而不是机械复述;回答时要提炼规则、说明口径,并在必要时指出来源。
4. 如果检索结果为空或证据冲突,必须明确告诉用户当前知识不足,不能编造业务规则。
5. 当问题会影响 SQL 过滤条件、指标定义、分析步骤时,优先调用该工具再继续生成回答或计划。
Expand Down
3 changes: 1 addition & 2 deletions data-agent-frontend/knip.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,5 @@
"$schema": "https://unpkg.com/knip@4/schema.json",
"entry": ["src/main.js", "src/**/*.vue", "vite.config.js"],
"project": ["src/**/*.{js,ts,vue}"],
"ignore": ["**/*.d.ts"],
"ignoreDependencies": ["@vitejs/plugin-vue", "vite"]
"ignore": ["**/*.d.ts"]
}
Loading
Loading