agent-html-drop: Instructions file for Codex

AGENTS.md

关键：本文件里凡 @path/to/file 形式的引用（如 @MEMORY/MEMORY.md），都用 Read 工具按需 读取——它们与你当前任务直接相关。不自动展开 @import 的 agent 尤须手动执行，否则漏上下文。

项目定位

agent-html-drop 是一个常驻 HTTP daemon：让本机 AI coding agent 通过 MCP（Streamable HTTP）把 yzr-md-to-html 等产出的自包含 HTML 推到远端 nginx server， 同时提供一个浏览器管理页（列表 / 预览 / 删除 / 复制公开 URL）与可选的浏览器侧批注。

前身是 yzr-agent-tools 仓库里的 html-mcp，2026-08 独立成单工具仓库并更名。

文档分层：本文件承载 agent 工作上下文（规约 / 命令 / 架构）；用户文档（安装 / 快速上手 / 命令一览 / 局限性）见根 README.md。设计文档在 docs/（design.md + tasks.md + 决策日志）。

仓库规约

• 测试绝不能触碰真实的服务配置（~/.config/agent-html-drop/——线上 daemon 的 config.toml / token 就在那里）。tests/conftest.py 的 autouse fixture 强制：snapshot 真实配置目录的 mtime，重定向 paths.* 到 tmp，测试结束后断言未变。
• Python 3.7+ 兼容。pyproject 固定 tomli>=1.1（<3.11 时）。CLI 用 stdlib argparse， 无第三方运行时依赖。禁 dict[str, str] 语法、walrus、match；用 from typing import Dict, List, Optional。
• config TOML 必须透传未知字段（config.py 读写往返不丢用户自定义键）。
• 原子写文件。TOML 与 docroot 文件都先写 .tmp 再 os.replace()，永远不出现半写状态。
• 路径穿越防护：所有文件名过 ^[A-Za-z0-9._-]+\.html$ regex，绝不拼接未校验的用户输入进路径。

• 跨会话需持久化的"为什么 / 边界规则"写入根目录 MEMORY/（MEMORY.md 是索引），禁写 agent 私有 memory——私有路径不随仓迁移 / 不进 git / 多 agent 各写各的会分裂成 N 份。
  • 完整 memory（设计决策 / 工作流约束）→ MEMORY/<slug>.md，带 frontmatter 三件套： name(=文件 slug) + description(≤200 字符事实摘要) + metadata.type(user|feedback|project|reference)
  • 短 memory（一句话事实）→ 直接写 MEMORY.md 索引行，不单独建文件

常用命令

# 容器化（2026-08-02 起为唯一种部署模式；详见 docs/design.md §15）。
# daemon 自服务 /files/*、nginx 退化为纯反代；TLS 在边缘 nginx 终结，容器内纯 HTTP。
docker compose up -d --build                    # 首次自动种 config + token（持久化在 ./data/）
docker compose exec agent-html-drop agent-html-drop token show   # 取 token（exec 不走 ENTRYPOINT，用 wrapper）
bash scripts/docker-smoke.sh                    # 容器冒烟（build→/api/health→/files→token，需 docker）

# 测试 — 需要 pytest + pytest-cov 自装（pip install --user pytest pytest-cov）。
# pyproject.toml 的 [tool.pytest.ini_options].pythonpath 已含 src/，
# 不需要 `pip install -e .` 也能 import agent_html_drop。
pytest
pytest tests/test_cli.py -v                   # 单文件
pytest --cov=agent_html_drop                  # 带覆盖率

# CLI 自身
agent-html-drop init                            # 初始化 ~/.config/agent-html-drop/,生成 bearer token
agent-html-drop serve                           # 前台启动 (Ctrl+C 停);生产建议 tmux / systemd 用户单元
agent-html-drop token show                      # 打印 token,配到 agent MCP config
agent-html-drop nginx-config                    # 打印 nginx 反代片段到 stdout
agent-html-drop nginx-config --write            # 写到 ~/.config/agent-html-drop/nginx.conf.example
agent-html-drop status                          # config / token / docroot 状态