feat: implement instruction assembly and project instruction providers with tests
This commit is contained in:
mlogclub
@@ -0,0 +1,112 @@
|
||||
package instruction
|
||||
|
||||
import "strings"
|
||||
|
||||
const defaultGovernanceInstruction = `
|
||||
你正在一个有明确工程约束的客服系统中工作。
|
||||
执行时必须严格遵守当前注入的项目规则、Agent 规则和技能规则。
|
||||
如果存在工具白名单限制，只能调用当前允许的工具；信息不足时优先追问，不要伪造事实或跳过必要确认。
|
||||
`
|
||||
|
||||
type Assembler struct {
|
||||
governanceInstruction string
|
||||
}
|
||||
|
||||
type AssemblerInput struct {
|
||||
AgentInstruction string
|
||||
GovernanceInstruction string
|
||||
SkillInstruction string
|
||||
ToolAppendices []string
|
||||
ProjectInstruction string
|
||||
}
|
||||
|
||||
type AssemblySummary struct {
|
||||
SectionTitles []string
|
||||
HasProjectRule bool
|
||||
HasGovernanceRule bool
|
||||
HasAgentRule bool
|
||||
HasSkillRule bool
|
||||
HasToolRule bool
|
||||
}
|
||||
|
||||
type AssemblyResult struct {
|
||||
Text string
|
||||
Summary AssemblySummary
|
||||
}
|
||||
|
||||
func NewAssembler() *Assembler {
|
||||
return &Assembler{governanceInstruction: strings.TrimSpace(defaultGovernanceInstruction)}
|
||||
}
|
||||
|
||||
func (a *Assembler) Build(input AssemblerInput) string {
|
||||
return a.Assemble(input).Text
|
||||
}
|
||||
|
||||
func (a *Assembler) Assemble(input AssemblerInput) AssemblyResult {
|
||||
parts := make([]string, 0, 5)
|
||||
summary := AssemblySummary{SectionTitles: make([]string, 0, 5)}
|
||||
projectInstruction := strings.TrimSpace(input.ProjectInstruction)
|
||||
if projectInstruction == "" {
|
||||
projectInstruction = strings.TrimSpace(DefaultProjectInstruction)
|
||||
}
|
||||
if projectInstruction != "" {
|
||||
parts = append(parts, buildInstructionSection("项目级规则", projectInstruction))
|
||||
summary.HasProjectRule = true
|
||||
summary.SectionTitles = append(summary.SectionTitles, "项目级规则")
|
||||
}
|
||||
governanceInstruction := strings.TrimSpace(input.GovernanceInstruction)
|
||||
if governanceInstruction == "" && a != nil {
|
||||
governanceInstruction = strings.TrimSpace(a.governanceInstruction)
|
||||
}
|
||||
if governanceInstruction != "" {
|
||||
parts = append(parts, buildInstructionSection("系统治理规则", governanceInstruction))
|
||||
summary.HasGovernanceRule = true
|
||||
summary.SectionTitles = append(summary.SectionTitles, "系统治理规则")
|
||||
}
|
||||
if agentInstruction := strings.TrimSpace(input.AgentInstruction); agentInstruction != "" {
|
||||
parts = append(parts, buildInstructionSection("Agent 规则", agentInstruction))
|
||||
summary.HasAgentRule = true
|
||||
summary.SectionTitles = append(summary.SectionTitles, "Agent 规则")
|
||||
}
|
||||
if skillInstruction := strings.TrimSpace(input.SkillInstruction); skillInstruction != "" {
|
||||
parts = append(parts, buildInstructionSection("当前技能上下文", skillInstruction))
|
||||
summary.HasSkillRule = true
|
||||
summary.SectionTitles = append(summary.SectionTitles, "当前技能上下文")
|
||||
}
|
||||
if appendix := buildToolAppendix(input.ToolAppendices); appendix != "" {
|
||||
parts = append(parts, buildInstructionSection("工具补充规则", appendix))
|
||||
summary.HasToolRule = true
|
||||
summary.SectionTitles = append(summary.SectionTitles, "工具补充规则")
|
||||
}
|
||||
return AssemblyResult{
|
||||
Text: strings.TrimSpace(strings.Join(parts, "\n\n")),
|
||||
Summary: summary,
|
||||
}
|
||||
}
|
||||
|
||||
func buildInstructionSection(title, body string) string {
|
||||
title = strings.TrimSpace(title)
|
||||
body = strings.TrimSpace(body)
|
||||
if body == "" {
|
||||
return ""
|
||||
}
|
||||
if title == "" {
|
||||
return body
|
||||
}
|
||||
return title + "：\n" + body
|
||||
}
|
||||
|
||||
func buildToolAppendix(input []string) string {
|
||||
if len(input) == 0 {
|
||||
return ""
|
||||
}
|
||||
parts := make([]string, 0, len(input))
|
||||
for _, item := range input {
|
||||
item = strings.TrimSpace(item)
|
||||
if item == "" {
|
||||
continue
|
||||
}
|
||||
parts = append(parts, item)
|
||||
}
|
||||
return strings.TrimSpace(strings.Join(parts, "\n\n"))
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
package instruction
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestAssemblerRespectsProvidedSources(t *testing.T) {
|
||||
result := NewAssembler().Assemble(AssemblerInput{
|
||||
ProjectInstruction: "project-rule",
|
||||
GovernanceInstruction: "governance-rule",
|
||||
AgentInstruction: "agent-rule",
|
||||
SkillInstruction: "skill-rule",
|
||||
ToolAppendices: []string{"tool-rule-1", "tool-rule-2"},
|
||||
})
|
||||
if !strings.Contains(result.Text, "项目级规则：\nproject-rule") {
|
||||
t.Fatalf("missing project instruction: %s", result.Text)
|
||||
}
|
||||
if !strings.Contains(result.Text, "系统治理规则：\ngovernance-rule") {
|
||||
t.Fatalf("missing governance instruction: %s", result.Text)
|
||||
}
|
||||
if !strings.Contains(result.Text, "当前技能上下文：\nskill-rule") {
|
||||
t.Fatalf("missing skill instruction: %s", result.Text)
|
||||
}
|
||||
if !strings.Contains(result.Text, "工具补充规则：\ntool-rule-1") {
|
||||
t.Fatalf("missing tool appendix: %s", result.Text)
|
||||
}
|
||||
if !result.Summary.HasProjectRule || !result.Summary.HasGovernanceRule || !result.Summary.HasAgentRule || !result.Summary.HasSkillRule || !result.Summary.HasToolRule {
|
||||
t.Fatalf("unexpected summary: %#v", result.Summary)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,85 @@
|
||||
package instruction
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
|
||||
runtimetooling "cs-agent/internal/ai/runtime/tooling"
|
||||
"cs-agent/internal/models"
|
||||
"cs-agent/internal/pkg/toolx"
|
||||
)
|
||||
|
||||
func BuildSelectedSkillActivationInstruction(skill *models.SkillDefinition) string {
|
||||
if skill == nil {
|
||||
return ""
|
||||
}
|
||||
lines := []string{
|
||||
"当前命中的专项技能：",
|
||||
fmt.Sprintf("- code: %s", strings.TrimSpace(skill.Code)),
|
||||
fmt.Sprintf("- name: %s", strings.TrimSpace(skill.Name)),
|
||||
}
|
||||
if desc := strings.TrimSpace(skill.Description); desc != "" {
|
||||
lines = append(lines, fmt.Sprintf("- description: %s", desc))
|
||||
}
|
||||
lines = append(lines, "", "执行要求：", "- 本轮优先处理该技能范围内的问题。", fmt.Sprintf("- 需要专项处理细节时，优先调用 %s 工具加载该技能说明后再继续。", toolx.BuiltinSkill.Name), "- 如果关键信息不足，先向用户追问。", "- 不得调用当前技能未授权的工具。")
|
||||
return strings.TrimSpace(strings.Join(lines, "\n"))
|
||||
}
|
||||
|
||||
func BuildSelectedSkillDocument(skill *models.SkillDefinition, toolDefinitions []runtimetooling.MCPToolDefinition) string {
|
||||
if skill == nil {
|
||||
return ""
|
||||
}
|
||||
lines := []string{
|
||||
"当前命中的专项技能：",
|
||||
fmt.Sprintf("- code: %s", strings.TrimSpace(skill.Code)),
|
||||
fmt.Sprintf("- name: %s", strings.TrimSpace(skill.Name)),
|
||||
}
|
||||
if desc := strings.TrimSpace(skill.Description); desc != "" {
|
||||
lines = append(lines, fmt.Sprintf("- description: %s", desc))
|
||||
}
|
||||
if content := strings.TrimSpace(skill.Instruction); content != "" {
|
||||
lines = append(lines, "", "技能说明：", content)
|
||||
}
|
||||
if examples := parseJSONStringArray(skill.Examples); len(examples) > 0 {
|
||||
lines = append(lines, "", "典型示例问法：")
|
||||
for _, item := range examples {
|
||||
lines = append(lines, "- "+item)
|
||||
}
|
||||
}
|
||||
if len(toolDefinitions) > 0 {
|
||||
lines = append(lines, "", "当前技能允许使用的工具：")
|
||||
for _, item := range toolDefinitions {
|
||||
if strings.TrimSpace(item.ToolCode) == "" {
|
||||
continue
|
||||
}
|
||||
line := "- " + strings.TrimSpace(item.ToolCode)
|
||||
if title := strings.TrimSpace(item.Title); title != "" {
|
||||
line += " | " + title
|
||||
}
|
||||
lines = append(lines, line)
|
||||
}
|
||||
}
|
||||
lines = append(lines, "", "执行要求：", "- 优先遵循该技能说明完成任务。", "- 如果关键信息不足，先向用户追问。", "- 不得调用当前技能未授权的工具。")
|
||||
return strings.TrimSpace(strings.Join(lines, "\n"))
|
||||
}
|
||||
|
||||
func parseJSONStringArray(raw string) []string {
|
||||
raw = strings.TrimSpace(raw)
|
||||
if raw == "" {
|
||||
return nil
|
||||
}
|
||||
var ret []string
|
||||
if err := json.Unmarshal([]byte(raw), &ret); err != nil {
|
||||
return nil
|
||||
}
|
||||
out := make([]string, 0, len(ret))
|
||||
for _, item := range ret {
|
||||
item = strings.TrimSpace(item)
|
||||
if item == "" {
|
||||
continue
|
||||
}
|
||||
out = append(out, item)
|
||||
}
|
||||
return out
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
package instruction
|
||||
|
||||
// DefaultProjectInstruction 为当前项目统一注入的全局项目规则。
|
||||
//
|
||||
// 默认回退到内置常量；运行时优先由 ProjectInstructionProvider 读取仓库中的 AGENTS.md。
|
||||
const DefaultProjectInstruction = `# AGENTS.md
|
||||
|
||||
本文件定义本项目内 AI Agent 的强制开发规则。除非用户明确要求偏离，否则必须遵循。
|
||||
|
||||
## 1. 基本原则
|
||||
|
||||
- 适用范围：仓库根目录及所有子目录
|
||||
- 优先级：用户明确指令 > 本文件 > 默认实现习惯
|
||||
- 若与用户要求冲突：先执行用户要求，并在变更说明中标注偏离点
|
||||
`
|
||||
@@ -0,0 +1,100 @@
|
||||
package instruction
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
|
||||
runtimetooling "cs-agent/internal/ai/runtime/tooling"
|
||||
"cs-agent/internal/models"
|
||||
"cs-agent/internal/pkg/toolx"
|
||||
)
|
||||
|
||||
type ProjectInstructionProvider struct {
|
||||
fileName string
|
||||
}
|
||||
|
||||
func NewProjectInstructionProvider() *ProjectInstructionProvider {
|
||||
return &ProjectInstructionProvider{fileName: "AGENTS.md"}
|
||||
}
|
||||
|
||||
func (p *ProjectInstructionProvider) Resolve() string {
|
||||
if text := p.loadFromFile(); text != "" {
|
||||
return text
|
||||
}
|
||||
return strings.TrimSpace(DefaultProjectInstruction)
|
||||
}
|
||||
|
||||
func (p *ProjectInstructionProvider) loadFromFile() string {
|
||||
path := p.resolvePath()
|
||||
if path == "" {
|
||||
return ""
|
||||
}
|
||||
data, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return ""
|
||||
}
|
||||
return strings.TrimSpace(string(data))
|
||||
}
|
||||
|
||||
func (p *ProjectInstructionProvider) resolvePath() string {
|
||||
fileName := "AGENTS.md"
|
||||
if p != nil && strings.TrimSpace(p.fileName) != "" {
|
||||
fileName = strings.TrimSpace(p.fileName)
|
||||
}
|
||||
wd, err := os.Getwd()
|
||||
if err != nil {
|
||||
return ""
|
||||
}
|
||||
dir := wd
|
||||
for {
|
||||
candidate := filepath.Join(dir, fileName)
|
||||
if stat, statErr := os.Stat(candidate); statErr == nil && !stat.IsDir() {
|
||||
return candidate
|
||||
}
|
||||
parent := filepath.Dir(dir)
|
||||
if parent == dir {
|
||||
return ""
|
||||
}
|
||||
dir = parent
|
||||
}
|
||||
}
|
||||
|
||||
type ToolAppendixProvider struct{}
|
||||
|
||||
func NewToolAppendixProvider() *ToolAppendixProvider {
|
||||
return &ToolAppendixProvider{}
|
||||
}
|
||||
|
||||
type GovernanceInstructionProvider struct{}
|
||||
|
||||
func NewGovernanceInstructionProvider() *GovernanceInstructionProvider {
|
||||
return &GovernanceInstructionProvider{}
|
||||
}
|
||||
|
||||
func (p *GovernanceInstructionProvider) Resolve() string {
|
||||
return strings.TrimSpace(defaultGovernanceInstruction)
|
||||
}
|
||||
|
||||
type SkillInstructionProvider struct{}
|
||||
|
||||
func NewSkillInstructionProvider() *SkillInstructionProvider {
|
||||
return &SkillInstructionProvider{}
|
||||
}
|
||||
|
||||
func (p *SkillInstructionProvider) Resolve(selectedSkill *models.SkillDefinition) string {
|
||||
return BuildSelectedSkillActivationInstruction(selectedSkill)
|
||||
}
|
||||
|
||||
func (p *ToolAppendixProvider) Build(toolDefinitions []runtimetooling.MCPToolDefinition, extraToolCodes map[string]string) []string {
|
||||
appendixParts := make([]string, 0, 1)
|
||||
toolCodes := make([]string, 0, len(toolDefinitions)+len(extraToolCodes))
|
||||
for _, item := range toolDefinitions {
|
||||
toolCodes = append(toolCodes, item.ToolCode)
|
||||
}
|
||||
for _, item := range extraToolCodes {
|
||||
toolCodes = append(toolCodes, item)
|
||||
}
|
||||
appendixParts = append(appendixParts, toolx.BuildToolAppendicesForCodes(len(toolDefinitions) > 0, toolCodes)...)
|
||||
return appendixParts
|
||||
}
|
||||
@@ -0,0 +1,48 @@
|
||||
package instruction
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestProjectInstructionProviderResolveFromAgentsFile(t *testing.T) {
|
||||
tmpDir := t.TempDir()
|
||||
nestedDir := filepath.Join(tmpDir, "nested", "child")
|
||||
if err := os.MkdirAll(nestedDir, 0o755); err != nil {
|
||||
t.Fatalf("mkdir failed: %v", err)
|
||||
}
|
||||
content := "# AGENTS.md\n\nfrom temp file"
|
||||
if err := os.WriteFile(filepath.Join(tmpDir, "AGENTS.md"), []byte(content), 0o644); err != nil {
|
||||
t.Fatalf("write file failed: %v", err)
|
||||
}
|
||||
wd, err := os.Getwd()
|
||||
if err != nil {
|
||||
t.Fatalf("getwd failed: %v", err)
|
||||
}
|
||||
defer func() { _ = os.Chdir(wd) }()
|
||||
if err := os.Chdir(nestedDir); err != nil {
|
||||
t.Fatalf("chdir failed: %v", err)
|
||||
}
|
||||
got := NewProjectInstructionProvider().Resolve()
|
||||
if !strings.Contains(got, "from temp file") {
|
||||
t.Fatalf("expected provider to load AGENTS.md from file, got: %s", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestProjectInstructionProviderFallbacksToDefault(t *testing.T) {
|
||||
tmpDir := t.TempDir()
|
||||
wd, err := os.Getwd()
|
||||
if err != nil {
|
||||
t.Fatalf("getwd failed: %v", err)
|
||||
}
|
||||
defer func() { _ = os.Chdir(wd) }()
|
||||
if err := os.Chdir(tmpDir); err != nil {
|
||||
t.Fatalf("chdir failed: %v", err)
|
||||
}
|
||||
got := NewProjectInstructionProvider().Resolve()
|
||||
if !strings.Contains(got, "本文件定义本项目内 AI Agent 的强制开发规则") {
|
||||
t.Fatalf("expected fallback project instruction, got: %s", got)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,86 @@
|
||||
package instruction
|
||||
|
||||
import (
|
||||
"strings"
|
||||
|
||||
runtimetooling "cs-agent/internal/ai/runtime/tooling"
|
||||
"cs-agent/internal/models"
|
||||
)
|
||||
|
||||
type Service struct {
|
||||
assembler *Assembler
|
||||
projectInstructionProvider *ProjectInstructionProvider
|
||||
governanceInstructionProvider *GovernanceInstructionProvider
|
||||
skillInstructionProvider *SkillInstructionProvider
|
||||
toolAppendixProvider *ToolAppendixProvider
|
||||
}
|
||||
|
||||
func NewService(
|
||||
assembler *Assembler,
|
||||
projectProvider *ProjectInstructionProvider,
|
||||
governanceProvider *GovernanceInstructionProvider,
|
||||
skillProvider *SkillInstructionProvider,
|
||||
toolProvider *ToolAppendixProvider,
|
||||
) *Service {
|
||||
if assembler == nil {
|
||||
assembler = NewAssembler()
|
||||
}
|
||||
if projectProvider == nil {
|
||||
projectProvider = NewProjectInstructionProvider()
|
||||
}
|
||||
if governanceProvider == nil {
|
||||
governanceProvider = NewGovernanceInstructionProvider()
|
||||
}
|
||||
if skillProvider == nil {
|
||||
skillProvider = NewSkillInstructionProvider()
|
||||
}
|
||||
if toolProvider == nil {
|
||||
toolProvider = NewToolAppendixProvider()
|
||||
}
|
||||
return &Service{
|
||||
assembler: assembler,
|
||||
projectInstructionProvider: projectProvider,
|
||||
governanceInstructionProvider: governanceProvider,
|
||||
skillInstructionProvider: skillProvider,
|
||||
toolAppendixProvider: toolProvider,
|
||||
}
|
||||
}
|
||||
|
||||
func (s *Service) Build(
|
||||
aiAgent *models.AIAgent,
|
||||
selectedSkill *models.SkillDefinition,
|
||||
toolDefinitions []runtimetooling.MCPToolDefinition,
|
||||
extraToolCodes map[string]string,
|
||||
) AssemblyResult {
|
||||
baseInstruction := ""
|
||||
if aiAgent != nil {
|
||||
baseInstruction = strings.TrimSpace(aiAgent.SystemPrompt)
|
||||
}
|
||||
projectInstruction := ""
|
||||
governanceInstruction := ""
|
||||
skillInstruction := ""
|
||||
toolAppendices := make([]string, 0)
|
||||
if s != nil && s.projectInstructionProvider != nil {
|
||||
projectInstruction = s.projectInstructionProvider.Resolve()
|
||||
}
|
||||
if s != nil && s.governanceInstructionProvider != nil {
|
||||
governanceInstruction = s.governanceInstructionProvider.Resolve()
|
||||
}
|
||||
if s != nil && s.skillInstructionProvider != nil {
|
||||
skillInstruction = s.skillInstructionProvider.Resolve(selectedSkill)
|
||||
}
|
||||
if s != nil && s.toolAppendixProvider != nil {
|
||||
toolAppendices = s.toolAppendixProvider.Build(toolDefinitions, extraToolCodes)
|
||||
}
|
||||
assembler := NewAssembler()
|
||||
if s != nil && s.assembler != nil {
|
||||
assembler = s.assembler
|
||||
}
|
||||
return assembler.Assemble(AssemblerInput{
|
||||
AgentInstruction: baseInstruction,
|
||||
GovernanceInstruction: governanceInstruction,
|
||||
SkillInstruction: skillInstruction,
|
||||
ToolAppendices: toolAppendices,
|
||||
ProjectInstruction: projectInstruction,
|
||||
})
|
||||
}
|
||||
Reference in New Issue
Block a user