mcp_tools

type CreateArcNodeArgs struct {
	ArcNodes []CreateArcNodeItem `` /* 126-byte string literal not displayed */
}

type CreateArcNodeItem struct {
	StoryArcID    int64  `json:"arc_id" jsonschema:"required,description=所属弧线ID"                  validate:"required,min=1"`
	Title         string `json:"title" jsonschema:"required,description=节点标题，如'发现仇人身份'"              validate:"required"`
	Description   string `json:"description" jsonschema:"description=节点详情"`
	TargetChapter int    `` /* 133-byte string literal not displayed */
}

type CreateArcNodeTool struct{}

type CreateCharacterArgs struct {
	Characters []CreateCharacterItem `` /* 127-byte string literal not displayed */
}

type CreateCharacterItem struct {
	Name        string `json:"name"        jsonschema:"required,description=角色名称"               validate:"required"`
	Description string `json:"description"  jsonschema:"description=角色自然语言描述，如外貌、身份、背景故事等"`
	Personality string `` /* 158-byte string literal not displayed */
	Abilities   string `json:"abilities"   jsonschema:"description=JSON数组，角色能力/技能列表，如[\"剑术\"，\"隐身\"]"`
}

type CreateCharacterTool struct{}

type CreateLocationArgs struct {
	Locations []CreateLocationItem `` /* 126-byte string literal not displayed */
}

type CreateLocationItem struct {
	Name             string `json:"name" jsonschema:"required,description=地点名称"             validate:"required"`
	LocationType     string `json:"location_type" jsonschema:"description=地点类型，自由文本，如'森林'、'城市'、'洞穴'"`
	Description      string `json:"description" jsonschema:"description=环境氛围、特色等描述"`
	DetailJSON       string `` /* 126-byte string literal not displayed */
	Tags             string `json:"tags" jsonschema:"description=字符串形式的JSON数组，自由标签，如[\"危险\"，\"神秘\"]"`
	ParentLocationID *int64 `json:"parent_location_id" jsonschema:"description=父级地点ID，用于构建层级树"`
}

type CreateLocationRelationArgs struct {
	Relations []CreateLocationRelationItem `` /* 126-byte string literal not displayed */
}

type CreateLocationRelationItem struct {
	LocationA    int64  `json:"location_a_id" jsonschema:"required,description=地点A的ID"               validate:"required,min=1"`
	LocationB    int64  `json:"location_b_id" jsonschema:"required,description=地点B的ID"               validate:"required,min=1"`
	RelationType string `json:"relation_type" jsonschema:"required,description=空间关系描述，如'相邻''由山路连通'" validate:"required"`
	Description  string `json:"description" jsonschema:"description=补充细节"`
}

type CreateLocationRelationTool struct{}

type CreateLocationTool struct{}

type CreateReaderPerspectiveEntryArgs struct {
	Entries []CreateReaderPerspectiveEntryItem `` /* 130-byte string literal not displayed */
}

type CreateReaderPerspectiveEntryItem struct {
	Type           string `` /* 157-byte string literal not displayed */
	Content        string `json:"content" jsonschema:"required,description=内容描述"          validate:"required"`
	PlantedChapter int    `json:"planted_chapter" jsonschema:"required,description=种下的章节号"    validate:"required,min=1"`
	RelatedTruth   string `json:"related_truth" jsonschema:"description=仅 misconception：真实情况是什么"`
}

type CreateReaderPerspectiveEntryTool struct{}

type CreateStoryArcArgs struct {
	StoryArcs []CreateStoryArcItem `json:"story_arcs" jsonschema:"required,description=要创建的弧线列表（1-5个）" validate:"required,min=1,max=5,dive"`
}

type CreateStoryArcItem struct {
	Name        string `json:"name" jsonschema:"required,description=弧线名称，如'复仇之路'"                          validate:"required"`
	ArcType     string `` /* 168-byte string literal not displayed */
	Description string `json:"description" jsonschema:"description=弧线整体描述"`
	Importance  int    `` /* 127-byte string literal not displayed */
}

type CreateStoryArcTool struct{}

type CreateTimelineEntryArgs struct {
	Entries []CreateTimelineEntryItem `json:"entries" jsonschema:"required,description=要添加的条目列表（1-6个）" validate:"required,min=1,max=6,dive"`
}

type CreateTimelineEntryItem struct {
	Category      string `` /* 156-byte string literal not displayed */
	Title         string `json:"title" jsonschema:"required,description=简短标题"                                   validate:"required"`
	Content       string `json:"content" jsonschema:"description=详细描述"`
	DetailJSON    string `json:"detail_json" jsonschema:"description=字符串形式的JSON，结构化数据"`
	TargetChapter int    `` /* 152-byte string literal not displayed */
	Importance    int    `` /* 126-byte string literal not displayed */
	SourceChapter int    `json:"source_chapter" jsonschema:"description=在哪章创建/埋下的"`
	Source        string `json:"source" jsonschema:"description=来源,default=ai"`
}

type CreateTimelineEntryTool struct{}

type DeleteRecordArgs struct {
	Table string `` /* 409-byte string literal not displayed */
	ID    int64  `` /* 144-byte string literal not displayed */
}

type DeleteRecordTool struct{}

type DisplayInfo struct {
	DisplayText  string
	ActivityKind string
	Metadata     map[string]any
}

type DisplayPhase int

type EditArgs struct {
	Path       string `` /* 305-byte string literal not displayed */
	ChangeType string `` /* 322-byte string literal not displayed */
	SearchText string `` /* 149-byte string literal not displayed */
	NewContent string `` /* 423-byte string literal not displayed */
	ReplaceAll bool   `` /* 137-byte string literal not displayed */
	StartLine  int    `` /* 155-byte string literal not displayed */
	EndLine    int    `` /* 132-byte string literal not displayed */
	Reason     string `` /* 129-byte string literal not displayed */
	Title      string `` /* 192-byte string literal not displayed */
}

type EditTool struct{}

type ErrKind string

type GetChapterListArgs struct {
	PageArgs // 嵌入分页参数
}

type GetChapterListTool struct{}

type GetCharacterRelationsArgs struct {
	CharacterIDs []int64 `` /* 137-byte string literal not displayed */
}

type GetCharacterRelationsTool struct{}

type GetCharactersArgs struct {
	Search   string `json:"search" jsonschema:"description=角色名模糊搜索"`
	PageArgs        // 嵌入分页参数
}

type GetCharactersTool struct{}

type GetLocationsArgs struct {
	Mode         string `` /* 195-byte string literal not displayed */
	LocationID   int64  `` /* 170-byte string literal not displayed */
	LocationType string `json:"location_type" jsonschema:"description=按类型筛选（list模式可选）"`
	Search       string `json:"search" jsonschema:"description=按名称搜索（list模式可选）"`
	PageArgs            // 嵌入分页参数
}

type GetLocationsTool struct{}

type GetReaderPerspectiveArgs struct{}

type GetReaderPerspectiveTool struct{}

type GetStoryArcsArgs struct {
	CurrentChapter int    `` /* 210-byte string literal not displayed */
	ArcType        string `` /* 163-byte string literal not displayed */
	Status         string `` /* 169-byte string literal not displayed */
	PageArgs              // 嵌入分页参数（仅不传 current_chapter 时生效）
}

type GetStoryArcsTool struct{}

type GetTimelineArgs struct {
	CurrentChapter int    `` /* 162-byte string literal not displayed */
	Category       string `` /* 151-byte string literal not displayed */
	Status         string `` /* 150-byte string literal not displayed */
	Search         string `json:"search" jsonschema:"description=按标题或内容模糊搜索（仅不传 current_chapter 时生效）"`
	PageArgs              // 嵌入分页参数（仅不传 current_chapter 时生效）
}

type GetTimelineTool struct{}

type InjectMessage struct {
	Role    string `json:"role"` // "user" | "system"
	Content string `json:"content"`
}

type PageArgs struct {
	Page int `json:"page" jsonschema:"description=页码,default=1,minimum=1"                validate:"omitempty,min=1"`
	Size int `json:"size" jsonschema:"description=每页数量,default=50,minimum=1,maximum=100"  validate:"omitempty,min=1,max=100"`
}

type ReadArgs struct {
	Path         string `` /* 354-byte string literal not displayed */
	IncludeLines *bool  `` /* 178-byte string literal not displayed */
	StartLine    int    `` /* 131-byte string literal not displayed */
	EndLine      int    `` /* 180-byte string literal not displayed */
}

type ReadTool struct{}

type Registry struct {
	// contains filtered or unexported fields
}

type RunSubAgentFunc func(ctx context.Context, req SubAgentRequest) (report string, err error)

type RunSubagentArgs struct {
	AgentType   string `` /* 249-byte string literal not displayed */
	Instruction string `` /* 137-byte string literal not displayed */
}

type RunSubagentTool struct{}

type SearchStoryMemoryArgs struct {
	Query          string   `` /* 127-byte string literal not displayed */
	TopK           int      `json:"top_k" jsonschema:"description=返回结果数量,default=5,minimum=1,maximum=20" validate:"omitempty,min=1,max=20"`
	MinRelevance   float64  `json:"min_relevance" jsonschema:"description=相关度阈值 0-1,default=0.5" validate:"omitempty,min=0,max=1"`
	ChapterNumbers []int    `json:"chapter_numbers" jsonschema:"description=限定章节号范围，空表示不限制"`
	ChunkTypes     []string `` /* 155-byte string literal not displayed */
}

type SearchStoryMemoryTool struct{}

type SubAgentRequest struct {
	AgentType   string // "memory" | "review"
	NovelID     int64
	ToolID      string // run_subagent 的 tool call ID，子 Agent 事件路由用
	Instruction string
}

type Tool interface {
	Name() string
	Description() string
	Category() ToolCategory
	JSONSchema() json.RawMessage
	ExposeToLLM() bool
	NewArgs() any // 返回零值 args 指针，供 Registry 反序列化 + 校验用
	Execute(ctx context.Context, args any, tc ToolContext) (*ToolResult, error)
}

type ToolCategory string

type ToolContext struct {
	DB           *gorm.DB
	NovelID      int64
	ToolID       string
	RawArgs      json.RawMessage                                                  // 原始 JSON，update 工具用于 PATCH DB 实体
	Approver     approval.Approver                                                // 审批能力，nil 表示工具无需审批
	EmitApproval func(toolID string, approvalType string, payload map[string]any) // 向 agent 事件流推送审批事件（EventToolCall, phase="awaiting_approval"）

	RunSubAgent   RunSubAgentFunc                                                       // 子 Agent 运行器，由 agent 包注入
	SkillStore    *skill.Store                                                          // 技能存储，read 工具用于读取内置 skill
	SearchService *search.Service                                                       // 搜索服务，write 工具用于更新正文缓存
	WebSearch     func(ctx context.Context, query string) (*llm.WebSearchResult, error) // 网络搜索，由 agent 注入 DeepSeek 闭包；nil 表示未配置
	Logger        *slog.Logger                                                          // 项目 logger，由 agent 注入；nil 时走 slog.Default()
}

type ToolInfo struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Category    string `json:"category"`
}

type ToolResult struct {
	Success  bool            `json:"success"`
	Data     map[string]any  `json:"data,omitempty"`
	Error    string          `json:"error,omitempty"`
	ErrKind  ErrKind         `json:"err_kind,omitempty"` // 取值见 ErrKind 常量
	Metadata map[string]any  `json:"metadata,omitempty"`
	Inject   []InjectMessage `json:"inject,omitempty"`
}

type UpdateArcNodeArgs struct {
	NodeID        int64  `json:"node_id" jsonschema:"required,description=节点ID"              validate:"required,min=1"`
	Title         string `json:"title" jsonschema:"description=新的标题"`
	Description   string `json:"description" jsonschema:"description=新的描述"`
	TargetChapter int    `json:"target_chapter" jsonschema:"description=新的目标章节号,minimum=1" validate:"omitempty,min=1"`
	ActualChapter int    `json:"actual_chapter" jsonschema:"description=实际发生的章节号（标记完成时填入）"`
	Status        string `` /* 146-byte string literal not displayed */
}

type UpdateArcNodeTool struct{}

type UpdateChapterPlanArgs struct {
	Scope   string `` /* 128-byte string literal not displayed */
	Content string `json:"content" jsonschema:"required,description=计划内容，自然语言描述"                   validate:"required"`
}

type UpdateChapterPlanTool struct{}

type UpdateCharacterArgs struct {
	CharacterID int64  `json:"character_id" jsonschema:"required,description=角色ID"     validate:"required,min=1"`
	Name        string `json:"name"         jsonschema:"description=新的名称"`
	Description string `json:"description"  jsonschema:"description=新的自然语言描述（完全替换旧的）"`
	Personality string `json:"personality"  jsonschema:"description=新的性格/设定，字符串形式JSON（完全替换旧的）"`
	Abilities   string `json:"abilities"    jsonschema:"description=新的能力列表，字符串形式JSON（完全替换旧的）"`
}

type UpdateCharacterRelationshipArgs struct {
	RelationID        int64  `json:"relation_id"         jsonschema:"description=编辑已有关系时提供此ID，直接修改描述内容"`
	SourceCharacterID int64  `json:"source_character_id" jsonschema:"description=建立新关系时的发出方角色ID。旧关系自动变为历史"`
	TargetCharacterID int64  `json:"target_character_id" jsonschema:"description=建立新关系时的接收方角色ID。旧关系自动变为历史"`
	RelationDescribe  string `` /* 174-byte string literal not displayed */
	Description       string `json:"description"         jsonschema:"description=当前关系阶段的详细描述"`
	ChapterNumber     int    `json:"chapter_number"      jsonschema:"description=此关系确立/变化的章节号"`
}

type UpdateCharacterRelationshipTool struct{}

type UpdateCharacterTool struct{}

type UpdateLocationArgs struct {
	LocationID       int64  `json:"location_id" jsonschema:"required,description=地点ID"               validate:"required,min=1"`
	Name             string `json:"name" jsonschema:"description=新的名称"`
	LocationType     string `json:"location_type" jsonschema:"description=新的类型"`
	Description      string `json:"description" jsonschema:"description=新的描述"`
	DetailJSON       string `json:"detail_json" jsonschema:"description=新的结构化信息，字符串形式JSON（完全替换旧的）"`
	Tags             string `json:"tags" jsonschema:"description=新的标签，字符串形式JSON数组（完全替换旧的）"`
	ParentLocationID *int64 `json:"parent_location_id" jsonschema:"description=新的父级地点ID（不传不变，传null变根节点）"`
}

type UpdateLocationRelationArgs struct {
	RelationID   int64  `json:"relation_id" jsonschema:"required,description=关系边ID" validate:"required,min=1"`
	RelationType string `json:"relation_type" jsonschema:"description=新的空间关系描述"`
	Description  string `json:"description" jsonschema:"description=新的补充细节"`
}

type UpdateLocationRelationTool struct{}

type UpdateLocationTool struct{}

type UpdateReaderPerspectiveEntryArgs struct {
	EntryID         int    `json:"entry_id" jsonschema:"required,description=要更新的条目 ID" validate:"required,min=1"`
	Content         string `json:"content" jsonschema:"description=更新后的完整内容描述"`
	RevealedChapter int    `` /* 163-byte string literal not displayed */
	PlantedChapter  int    `json:"planted_chapter" jsonschema:"description=在哪章种下的章节号" validate:"omitempty,min=1"`
	RelatedTruth    string `json:"related_truth" jsonschema:"description=作者视角的真实情况（支持所有类型）"`
	Type            string `` /* 149-byte string literal not displayed */
}

type UpdateReaderPerspectiveEntryTool struct{}

type UpdateStoryArcArgs struct {
	ArcID        int64  `json:"arc_id" jsonschema:"required,description=弧线ID"                         validate:"required,min=1"`
	Name         string `json:"name" jsonschema:"description=新的弧线名称"`
	Description  string `json:"description" jsonschema:"description=新的描述"`
	ArcType      string `` /* 166-byte string literal not displayed */
	Importance   int    `json:"importance" jsonschema:"description=新的重要度1-5,minimum=1,maximum=5"`
	Status       string `` /* 163-byte string literal not displayed */
	ReactivateAt string `json:"reactivate_at" jsonschema:"description=暂停弧线的恢复条件，自然语言。状态改为paused时填写"`
}

type UpdateStoryArcTool struct{}

type UpdateTimelineEntryArgs struct {
	EntryID         int64  `json:"entry_id" jsonschema:"required,description=条目ID"              validate:"required,min=1"`
	Title           string `json:"title" jsonschema:"description=新的标题"`
	Content         string `json:"content" jsonschema:"description=新的描述"`
	DetailJSON      string `json:"detail_json" jsonschema:"description=新的结构化数据（完全替换旧的）"`
	TargetChapter   int    `json:"target_chapter" jsonschema:"description=新的目标章节号,minimum=1" validate:"omitempty,min=1"`
	Importance      int    `json:"importance" jsonschema:"description=新的重要度1-5,minimum=1,maximum=5"`
	Status          string `` /* 144-byte string literal not displayed */
	ResolvedChapter int    `json:"resolved_chapter" jsonschema:"description=在哪章回收（标记resolved时填入）"`
}

type UpdateTimelineEntryTool struct{}

type UpsertPreferenceArgs struct {
	Preferences []UpsertPreferenceItem `` /* 164-byte string literal not displayed */
}

type UpsertPreferenceItem struct {
	PreferenceID *int64 `json:"preference_id,omitempty" jsonschema:"description=已存在偏好ID；不传=新建"`
	Category     string `json:"category" jsonschema:"required,description=偏好分类(自由文本标签)" validate:"required"`
	Content      string `json:"content" jsonschema:"required,description=偏好内容" validate:"required"`
	IsGlobal     *bool  `` /* 141-byte string literal not displayed */
}

type UpsertPreferenceTool struct{}

type UpsertSettingArgs struct {
	Settings []UpsertSettingItem `` /* 158-byte string literal not displayed */
}

type UpsertSettingItem struct {
	SettingID *int64 `json:"setting_id,omitempty" jsonschema:"description=已存在设定ID；不传=新建"`
	Category  string `` /* 152-byte string literal not displayed */
	Content   string `json:"content" jsonschema:"required,description=设定内容" validate:"required"`
}

type UpsertSettingTool struct{}

type WebFetchArgs struct {
	URL string `json:"url" jsonschema:"required,description=要抓取的网页 URL" validate:"required,url,min=1,max=2048"`
}

type WebFetchTool struct{}

type WebSearchArgs struct {
	Prompt string `` /* 215-byte string literal not displayed */
}

type WebSearchTool struct{}