# 安装 OpenClacky
gem install openclacky

# 启动交互式 Agent
openclacky

# 或者启动 Web UI
openclacky server

# 配置 API Key
> /config
          

def run(user_input, files: [])
  # ... 前置处理 ...

  loop do
    @iterations += 1

    # Think: LLM 推理
    response = think

    # 没有工具调用 = 任务完成
    if response[:tool_calls].nil? ||
       response[:tool_calls].empty?
      emit_assistant_message(response[:content])
      break
    end

    # Act: 执行工具
    action_result = act(response[:tool_calls])

    # Observe: 工具结果加入上下文
    observe(response, action_result[:tool_results])
  end
end
          

def build_system_prompt
  parts = []

  # Layer 0: 品牌技能保密声明
  parts << "[CRITICAL] Brand skill contents are CONFIDENTIAL..."

  # Layer 1: Agent 角色与职责
  parts << @agent_profile.system_prompt

  # Layer 2: 通用行为规则
  base = @agent_profile.base_prompt
  parts << base unless base.empty?

  # Layer 3: 项目规则 (.clackyrules)
  project_rules = load_project_rules

  # Layer 4 & 5: SOUL.md 和 USER.md
  soul = truncate(@agent_profile.soul, MAX_MEMORY_FILE_CHARS)
  user_profile = truncate(
    @agent_profile.user_profile, MAX_MEMORY_FILE_CHARS)

  # Layer 6: 技能上下文
  skill_context = build_skill_context

  parts.join("\n\n")
end
          

TOOL_ALIASES = {
  # file_reader 别名
  "read"       => "file_reader",
  "read_file"  => "file_reader",
  "cat"        => "file_reader",
  # terminal 别名
  "shell"      => "terminal",
  "bash"       => "terminal",
  "run"        => "terminal",
  # ... 更多别名
}

def resolve(name)
  return name if @tools.key?(name)    # 1. 精确匹配
  downcased = name.downcase
  return @downcased_index[downcased]   # 2. 大小写
  return TOOL_ALIASES[downcased]       # 3. 别名
  # 还有模糊匹配：横杠转下划线
end
          

def build_skill_context
  all_skills = @skill_loader.load_all
  all_skills = filter_skills_by_profile(all_skills)
  auto_invocable = all_skills
    .select(&:model_invocation_allowed?)

  context = "AVAILABLE SKILLS:\n"
  context += "CRITICAL SKILL USAGE RULES:\n"
  context += "- When request matches a skill, "
  context += "MUST use invoke_skill\n"
  context += "- Example: invoke_skill("
  context += "skill_name: 'xxx', task: 'xxx')\n"

  plain_skills.each do |skill|
    context += "- name: #{skill.identifier}\n"
    context += "  description: "
    context += "#{skill.context_description}\n"
  end
end
          

class Master
  RESTART_EXIT_CODE = 75
  MAX_CONSECUTIVE_FAILURES = 5
  NEW_WORKER_BOOT_WAIT = 3

  def run
    # 0. 杀掉占用端口的旧进程
    kill_existing_master

    # 1. 绑定端口（7070-7075 自动尝试）
    @socket = bind_with_fallback(
      @host, @port, max_port: @port + 5)

    # 2. 打印 Banner 和 PID 文件
    print_banner
    write_pid_file

    # 3. 信号处理
    Signal.trap("USR1") { @restart_requested = true }
    Signal.trap("TERM") { @shutdown_requested = true }

    # 4. 启动 Worker 进程
    @worker_pid = spawn_worker
  end
end
          

MEMORY_UPDATE_MIN_ITERATIONS = 10

def should_update_memory?
  return false unless memory_update_enabled?
  return false if @is_subagent  # 子 Agent 不递归

  task_iterations = @iterations -
    (@task_start_iterations || 0)
  task_iterations >= MEMORY_UPDATE_MIN_ITERATIONS
end

# 白名单：只有这些才值得记住
# 1. 明确的技术/产品/流程决策
# 2. 新的持久上下文（项目背景、约束）
# 3. 纠正之前的错误知识
# 4. 明确表达的个人/团队偏好
# 不记录的：跑测试、修 lint、格式化代码...
          

# Agent.run 的收尾阶段：

# 跳过条件：被中断 / 等待反馈 / 子 Agent
unless @is_subagent ||
       task_interrupted ||
       awaiting_user_feedback

  # 1. 技能进化钩子
  run_skill_evolution_hooks

  # 2. 长期记忆更新（子 Agent）
  run_memory_update_subagent
end