[ZhaoXingPeng]

关联 Issue

Closes #93

背景（Situation）

MCP 已提供并测试 ai_summarize_schema、ai_infer_business_names、ai_recommend_template 和 ai_metrics，但 java-codegen-from-db Skill 仍标注阶段 4 工具未实现，并要求跳过语义增强。按 Skill 执行的客户端因此无法使用已存在的能力，文档与工具 schema 不一致。

任务（Task）

同步语义增强工作流与当前 MCP schema，保留规则优先和无 API key 路径，并把结果展示和用户确认作为进入代码生成的前置条件。

行动（Action）

• 更新 Skill 的阶段 3 参数、返回字段和 prefer_llm 可选语义。
• 明确命名、模板推荐和 schema 摘要必须先展示，再等待用户确认。
• 新增 Skill 工作流契约测试，防止工具与文档再次漂移。
• 没有做什么：不修改 AI 推断算法、模型、缓存、数据库访问或性能目标。

验证（Verification）

环境：Windows 11，Python 3.12.12。

• PYTHONPATH=src python -m pytest tests/unit/ -q：631 passed。
• AI 与 Skill 定向契约测试：86 passed。
• ruff check src tests 与 git diff --check：通过。

实验与证据（Evidence）

用无 API key 的规则优先输入执行 Skill 契约，工具名称、必填参数和 prefer_llm=false 均与当前注册表一致；生成阶段只有在确认结果后才可继续。未执行真实 LLM 调用，也没有性能基准，因此不作质量或速度结论。

兼容性、风险与回滚

• 公共 API / 数据格式 / 迁移：只更新 Skill 和契约测试，不改变 MCP payload。
• 风险与已知限制：客户端是否渲染确认步骤仍取决于客户端实现；LLM 路径未在本 PR 验证。
• 回滚：revert 对应文档和测试提交即可。
• 后续 Issue：如需统一各 Skill 的阶段状态，应另建 docs/governance Issue。

[ZhaoXingPeng]

问题复核：当前仓库的 get_ai_tools() 已注册 ai_infer_business_names、ai_recommend_template、ai_summarize_schema 和 ai_metrics，对应单测也已存在；但主 Skill 仍写“Phase 4 工具尚未实现，跳过本阶段”，因此按文档执行会稳定漏掉已上线能力。

[ZhaoXingPeng]

契约同步：Skill 现在按实际 handler schema 描述 table_names、foreign_keys、table_column_counts、prefer_llm 和 hint_modern_stack，并列出 narrative、class_name、recommended_template 等返回字段。默认规则路径不需要 API key，只有用户明确同意才启用 prefer_llm=true。

[ZhaoXingPeng]

验证记录：新增 2 项 Skill 契约测试，检查阶段 3 不再声明跳过，并检查 AI 参数、返回字段和用户确认要求；全量 PYTHONPATH=src python -m pytest -q tests/unit 为 631 passed。该 PR 不修改 AI 算法，性能未测量，也不宣称性能提升。