Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.
JavaScript agent-orchestrationagentic-workflowai-agentsai-codingclaude-codecode-reviewcodebuddycodexcoding-agentscursordeveloper-toolshuman-on-the-loopllmmcpmulti-agentsdlcself-hostedsopworkflow-automationworkflow-engine
package httpapi
import (
"bytes"
"encoding/json"
"fmt"
"io"
"strings"
"unicode/utf8"
"agentflow/internal/domain"
)
const (
agentToolMaxQuestions = 12
agentToolMaxOptions = 10
agentToolMaxQuestionLen = 500
agentToolMaxOptionLen = 200
agentToolMaxSummaryLen = 4000
agentToolMaxMessageLen = 20000
agentToolMaxPayload = 256 << 10
agentToolMaxDrafts = assistantMaxBatch
)
const (
submitClarificationTool = "submit_clarification"
submitAssistantReplyTool = "submit_assistant_reply"
submitNotificationReportTool = "submit_notification_report"
)
func terminalToolDescriptors(mode AgentToolMode, exec assistantExecMode) []agentToolDescriptor {
switch mode {
case AgentToolReport:
schema, _ := json.Marshal(map[string]any{"type": "object", "additionalProperties": false, "required": []string{"body"}, "properties": map[string]any{
"title": map[string]any{"type": "string", "maxLength": 200}, "summary": map[string]any{"type": "string", "maxLength": 4000}, "body": map[string]any{"type": "string", "minLength": 1, "maxLength": 20000},
}})
return []agentToolDescriptor{{Name: submitNotificationReportTool, Description: "提交本次 SOP 的整体成果报告。body 必填,可使用 Markdown;只汇总已提供的资料。校验失败时修正参数重新提交,成功后本轮结束。", InputSchema: schema, Kind: "terminal", Terminal: true, UpstreamName: submitNotificationReportTool}}
case AgentToolClarify:
schema, _ := json.Marshal(submitClarificationSchema())
return []agentToolDescriptor{{
Name: submitClarificationTool,
Description: "调用本工具提交本轮澄清结论。ready=true 时提供 summary;否则必须提供具体问题,不能只在 summary 里描述缺口。选择题提供至少两个不同的 options;需要用户填写路径、数量等内容时设 freeText=true、options=[]。校验失败时修正参数重新调用,提交成功才结束本轮。",
InputSchema: schema,
Kind: "terminal",
Terminal: true,
UpstreamName: submitClarificationTool,
}}
case AgentToolAssistant:
schema, _ := json.Marshal(submitAssistantReplySchema(exec))
return []agentToolDescriptor{{
Name: submitAssistantReplyTool,
Description: submitAssistantReplyDescription(exec),
InputSchema: schema,
Kind: "terminal",
Terminal: true,
UpstreamName: submitAssistantReplyTool,
}}
default:
return nil
}
}
// submitAssistantReplyDescription 按会话执行模式描述 drafts 的用途:
// confirm 全部走草稿;assisted 审查未通过时转草稿;auto 完全不用草稿。
// 工具描述是模型选择直连写入还是提交草稿的关键信号,必须与网关的
// 写入拦截策略一致。
func submitAssistantReplyDescription(exec assistantExecMode) string {
switch {
case exec.ReviewWrites:
return "仅用本工具提交需要用户确认的写入草稿,成功后本轮结束。当前为帮我批准模式:直接调用平台写入工具,独立 AI 审查具体操作和对话授权,通过后执行;未批准或审查不可用时才放入 drafts(每轮最多 1 个,含完整参数)供用户确认。不要绕过审查,不接受空 drafts 或进度占位回复。"
case exec.AutoWrite && !exec.ConfirmDangerous:
return "本工具仅用于提交待确认写入草稿,成功后立即结束本轮。当前为完全权限模式,平台写入工具已授权直接调用执行;完成全部操作后用自然语言汇总实际结果,不要调用本工具,不接受空 drafts 或进度占位回复。"
case exec.AutoWrite && exec.ConfirmDangerous:
return "仅用本工具提交待确认写入草稿,成功后立即结束本轮。保存类平台写入工具直接调用即生效;只有被平台拦截的危险写入(删除/发布/派发/启动)才放入 drafts(每轮最多 1 个,附完整参数,删除类需先自查引用并携带目标 id)供用户确认。message 汇总实际结果和待确认操作。不接受空 drafts 或进度占位回复;其余情况用自然语言回复并继续完成用户请求。"
default:
return "仅用本工具提交待确认写入草稿,成功后立即结束本轮。需要写入平台时把操作放入 drafts(每轮最多 1 个草稿,提交删除类操作前先用只读工具检查引用依赖),用户确认后才会执行。message 说明实际查询结果和待确认操作。不接受空 drafts 或进度占位回复;普通问答和只读查询用自然语言回复。提交草稿前用 workbench_tool_schema 查询该操作的准确参数,并提供 body/path/query 包装。"
}
}
func submitClarificationSchema() map[string]any {
return map[string]any{
"type": "object",
"additionalProperties": false,
"required": []string{"summary", "questions", "ready"},
"properties": map[string]any{
"summary": map[string]any{"type": "string", "description": "面向用户的简短分析结论"},
"questions": map[string]any{
"type": "array",
"maxItems": agentToolMaxQuestions,
"items": map[string]any{
"type": "object",
"additionalProperties": false,
"required": []string{"id", "question", "options", "multiSelect"},
"properties": map[string]any{
"id": map[string]any{"type": "string", "minLength": 1},
"question": map[string]any{"type": "string", "minLength": 1},
"options": map[string]any{"type": "array", "items": map[string]any{"type": "string", "minLength": 1}, "maxItems": agentToolMaxOptions},
"multiSelect": map[string]any{"type": "boolean"},
"freeText": map[string]any{"type": "boolean", "description": "开放填写题设为 true 且 options=[];默认是选择题,options 至少提供两个不同的可操作选项"},
},
},
},
"ready": map[string]any{"type": "boolean", "description": "本需求自身的范围已经足够开工时为 true,并在 summary 给出澄清结论"},
},
}
}
// submitAssistantReplySchema offers SOP proposals only where the user
// answers them: full access starts a SOP without asking.
func submitAssistantReplySchema(exec assistantExecMode) map[string]any {
names := assistantWriteToolNameList()
toolSchema := map[string]any{"type": "string", "description": "必填:本草稿要执行的写入工具名称,如 issues_save、issues_dispatch;不要省略,不带 mcp__ 前缀"}
if len(names) > 0 {
enum := make([]any, 0, len(names)+1)
for _, name := range names {
enum = append(enum, name)
}
enum = append(enum, "assistant_tasks_save")
toolSchema["enum"] = enum
}
draft := map[string]any{
"tool": toolSchema,
"path": map[string]any{"type": "object"},
"query": map[string]any{"type": "object"},
"body": map[string]any{},
}
if !exec.AutoWrite || exec.ReviewWrites {
draft["proposal"] = assistantProposalSchema()
}
return map[string]any{
"type": "object",
"additionalProperties": false,
"required": []string{"message", "drafts"},
"properties": map[string]any{
"message": map[string]any{"type": "string", "description": "展示给用户的 Markdown 文本"},
"drafts": map[string]any{
"type": "array",
"minItems": 1,
"maxItems": agentToolMaxDrafts,
"items": map[string]any{
"type": "object",
"additionalProperties": false,
"required": []string{"tool"},
"properties": draft,
},
},
},
}
}
func assistantWriteToolNameList() []string {
names := make([]string, 0, len(assistantWriteOperations))
for name := range assistantWriteOperations {
names = append(names, name)
}
return names
}
func parseSubmitClarificationArgs(raw json.RawMessage) (clarifyModelResult, error) {
if err := rejectOversizedAgentToolPayload(raw); err != nil {
return clarifyModelResult{}, err
}
if jsonHasKey(raw, "mcpCalls") {
return clarifyModelResult{}, fmt.Errorf("submit_clarification 不接受 mcpCalls")
}
var payload struct {
Summary string `json:"summary"`
Questions []domain.ClarificationQuestion `json:"questions"`
Ready bool `json:"ready"`
}
if err := json.Unmarshal(raw, &payload); err != nil {
return clarifyModelResult{}, fmt.Errorf("submit_clarification 参数无效: %w", err)
}
result := clarifyModelResult{
Summary: strings.TrimSpace(payload.Summary),
Questions: sanitizeClarificationQuestions(payload.Questions),
Ready: payload.Ready,
}
if utf8.RuneCountInString(result.Summary) > agentToolMaxSummaryLen {
result.Summary = string([]rune(result.Summary)[:agentToolMaxSummaryLen])
}
if err := validateSubmitClarification(result); err != nil {
return clarifyModelResult{}, err
}
rawMap := map[string]any{
"summary": result.Summary,
"questions": result.Questions,
"ready": result.Ready,
}
result.raw = rawMap
return result, nil
}
func validateSubmitClarification(result clarifyModelResult) error {
if strings.TrimSpace(result.Summary) != "" {
if result.Ready {
return nil
}
} else if result.Ready {
return fmt.Errorf("ready 结论缺少 summary")
}
if len(result.Questions) == 0 {
return fmt.Errorf("ready=false 时 questions 至少需要一个具体问题,不能只提交 summary。请补齐问题及选项后重新调用 submit_clarification;开放填写题使用 freeText=true、options=[]")
}
seen := map[string]bool{}
for _, q := range result.Questions {
id := strings.TrimSpace(q.ID)
if id == "" {
return fmt.Errorf("问题缺少 id")
}
if seen[id] {
return fmt.Errorf("问题 id 重复: %s", id)
}
seen[id] = true
if strings.TrimSpace(q.Question) == "" {
return fmt.Errorf("问题文本为空")
}
if utf8.RuneCountInString(q.Question) > agentToolMaxQuestionLen {
return fmt.Errorf("问题过长")
}
if len(q.Options) > agentToolMaxOptions {
return fmt.Errorf("单个问题选项过多")
}
if q.FreeText {
if len(q.Options) != 0 || q.MultiSelect {
return fmt.Errorf("问题 %s:freeText=true 的填写题应使用 options=[]、multiSelect=false", id)
}
} else {
options := map[string]bool{}
for _, option := range q.Options {
if option = strings.TrimSpace(option); option != "" {
options[option] = true
}
}
if len(options) < 2 {
return fmt.Errorf("问题 %s:选择题 options 至少需要两个不同的选项,请补齐后重新调用 submit_clarification;开放填写题使用 freeText=true、options=[]", id)
}
}
}
if len(result.Questions) > agentToolMaxQuestions {
return fmt.Errorf("问题数量超过 %d", agentToolMaxQuestions)
}
return nil
}
func sanitizeClarificationQuestions(in []domain.ClarificationQuestion) []domain.ClarificationQuestion {
out := make([]domain.ClarificationQuestion, 0, len(in))
for _, q := range in {
q.ID = strings.TrimSpace(q.ID)
q.Question = strings.TrimSpace(q.Question)
opts := make([]string, 0, len(q.Options))
for _, opt := range q.Options {
opt = strings.TrimSpace(opt)
if opt == "" {
continue
}
if utf8.RuneCountInString(opt) > agentToolMaxOptionLen {
opt = string([]rune(opt)[:agentToolMaxOptionLen])
}
opts = append(opts, opt)
}
q.Options = opts
if q.ID == "" && q.Question == "" && len(q.Options) == 0 {
continue
}
out = append(out, q)
}
return out
}
func parseSubmitAssistantReplyArgs(raw json.RawMessage, projectID string) (assistantReply, error) {
if err := rejectOversizedAgentToolPayload(raw); err != nil {
return assistantReply{}, err
}
var payload assistantReply
if err := json.Unmarshal(raw, &payload); err != nil {
return assistantReply{}, fmt.Errorf("submit_assistant_reply 参数无效: %w", err)
}
if jsonHasKey(raw, "lookups") || jsonHasKey(raw, "mcpCalls") {
return assistantReply{}, fmt.Errorf("submit_assistant_reply 不接受 lookups 或 mcpCalls")
}
payload.Message = strings.TrimSpace(payload.Message)
if payload.Message == "" {
return assistantReply{}, fmt.Errorf("message 不能为空")
}
if utf8.RuneCountInString(payload.Message) > agentToolMaxMessageLen {
payload.Message = string([]rune(payload.Message)[:agentToolMaxMessageLen])
}
if payload.Drafts == nil {
payload.Drafts = []assistantDraft{}
}
if err := validateAssistantBatch(payload); err != nil {
return assistantReply{}, err
}
for i := range payload.Drafts {
if err := validateAssistantDraft(&payload.Drafts[i], projectID); err != nil {
return assistantReply{}, err
}
}
return payload, nil
}
func jsonHasKey(raw json.RawMessage, key string) bool {
var obj map[string]json.RawMessage
if json.Unmarshal(raw, &obj) != nil {
return false
}
_, ok := obj[key]
return ok
}
func rejectOversizedAgentToolPayload(raw json.RawMessage) error {
if len(raw) > agentToolMaxPayload {
return fmt.Errorf("工具参数过大")
}
return nil
}
func parseSubmitNotificationReportArgs(raw json.RawMessage) (domain.AINotificationContent, error) {
var report domain.AINotificationContent
if err := rejectOversizedAgentToolPayload(raw); err != nil {
return report, err
}
decoder := json.NewDecoder(bytes.NewReader(raw))
decoder.DisallowUnknownFields()
if err := decoder.Decode(&report); err != nil {
return report, fmt.Errorf("报告参数无效")
}
if err := decoder.Decode(new(any)); err != io.EOF {
return report, fmt.Errorf("报告参数必须是单个 JSON 对象")
}
report.Title = strings.TrimSpace(report.Title)
report.Summary = strings.TrimSpace(report.Summary)
report.Body = strings.TrimSpace(report.Body)
if report.Body == "" {
return report, fmt.Errorf("body 不能为空,请填写整体报告后重新提交")
}
if utf8.RuneCountInString(report.Title) > 200 || utf8.RuneCountInString(report.Summary) > 4000 || utf8.RuneCountInString(report.Body) > 20000 {
return report, fmt.Errorf("报告超过长度限制:title 200、summary 4000、body 20000 字符")
}
return report, nil
}