"""plugins/ 目录首次创建时的 README 与 _template 示例（幂等）。"""

from __future__ import annotations

from pathlib import Path

_README = """# Aicd HOME 插件目录

每个插件占用一个子目录，目录名与 ``plugin.yaml`` 中的 ``id`` 一致（建议小写、数字、短横线、下划线）。

## 布局

- ``plugin.yaml``：必填。字段含 **id**、**name**、可选 **display_name** / **title**（展示用标题）、**description**、**version**、**enabled**、**min_aicd_version**、**entries**、**config**。
- ``PROMPT.md`` / ``SKILL.md``：可选。合并进系统提示，扩展 AI 行为说明。
- ``tools.json``：可选。OpenAI function 定义列表（与内置工具合并；函数名会自动加 ``plugin_<id>__`` 前缀）。
- ``handlers.py``：可选。导出 ``HANDLERS`` 字典，键为 ** tools.json 中的原始函数名**（无前缀），值为 ``(router, args) -> dict``。

- ``logs/``：装载失败、``plugin_<id>__…`` 工具返回失败或异常时写入 **YYYY-MM-DD.log**（UTC）；默认保留 **7** 天（**config.yaml** **plugins.logRetentionDays**）。**plugin_read_log** / **plugin_info** 可查看。

安全：仅安装可信来源的插件；启用 ``handlers.py`` 需在 ``config.yaml`` 中 ``plugins.allow_python_handlers: true``。

备份：修改插件前请使用 ``plugin_backup_now`` 或通过工具恢复；备份位于 ``plugins/.backups/<id>/``。

完整编写规范与自检清单见 **Aicd 源码仓库** ``docs/PLUGIN_AUTHORING_SPEC.md``（人机共同维护；实现变更时请同步更新该文档）。
"""

_TEMPLATE_YAML = """schema_version: 1
id: _template
name: template-bundle
display_name: Template (copy me)
version: 0.0.1
enabled: false
description: Duplicate this folder as plugins/<your_id>/ and edit plugin.yaml id/name.
entries:
  prompt_file: PROMPT.md
  skill_file: SKILL.md
  tools_file: tools.json
  handlers_py: handlers.py
config: {}
"""

_TEMPLATE_PROMPT = """<!-- 复制本目录为新 id 后编辑；此内容会附加到系统提示 -->
"""

_TEMPLATE_SKILL = """# Skill 片段（可选）

与 Cursor Skill 类似的说明，可与 PROMPT 一并注入主 Agent。
"""

_TEMPLATE_TOOLS = "[]\n"

_TEMPLATE_HANDLERS = '''"""示例：与 tools.json 中 function.name 对应的处理器键名一致（无前缀）。"""

from __future__ import annotations

from typing import Any


def example_tool(router: Any, args: dict[str, Any]) -> dict[str, Any]:
    return {"ok": True, "echo": args}


HANDLERS = {
    "example_tool": example_tool,
}
'''


def ensure_plugins_readme_and_template(plugins_root: Path) -> None:
    readme = plugins_root / "README.md"
    if not readme.is_file():
        readme.write_text(_README, encoding="utf-8", newline="\n")
    tmpl = plugins_root / "_template"
    if not tmpl.is_dir():
        tmpl.mkdir(parents=True, exist_ok=True)
    (tmpl / "plugin.yaml").write_text(_TEMPLATE_YAML, encoding="utf-8", newline="\n")
    p = tmpl / "PROMPT.md"
    if not p.is_file():
        p.write_text(_TEMPLATE_PROMPT, encoding="utf-8", newline="\n")
    s = tmpl / "SKILL.md"
    if not s.is_file():
        s.write_text(_TEMPLATE_SKILL, encoding="utf-8", newline="\n")
    tj = tmpl / "tools.json"
    if not tj.is_file():
        tj.write_text(_TEMPLATE_TOOLS, encoding="utf-8", newline="\n")
    th = tmpl / "handlers.py"
    if not th.is_file():
        th.write_text(_TEMPLATE_HANDLERS, encoding="utf-8", newline="\n")
