AGENTS：AI 任务运维约定

AGENTS.md 是 workspace C-Windows 的运维约定文档，用于给后续 AI 会话和任务提供背景约束，减少重复出错。它不提供可执行程序，而是把家用实验室的机器角色、AI 调用出口、文档写法、改动备份和已知待办集中写清楚。文档要求 AI 调用一律走本机网关：OpenAI 协议使用 http://127.0.0.1:8100/v1，Anthropic 协议使用 http://127.0.0.1:8100/v1/messages，Docker 容器改用 172.17.0.1 对应地址；不要新增直连 api.deepseek.com 的代码，除非用户明确要求并说明原因。每个服务使用独立虚拟 key，真 key 只放在 /opt/ai-gateway/secret.key，任何密钥都不进入文档、代码、Git 或聊天。文档还规定任务报告命名、配置改动前备份、systemd 与网关重启要求，并列出 2026-10-25 的待办。现状是约定已形成，AI 网关已上线并接入博客站、Open WebUI、AQF、stock_quant（配置）和 DSH，部分待办仍待处理。

功能

• 机器与角色速查：四台机器分别承担主服务器、NAS、Windows 自动化和 HK VPS 角色
• AI 调用统一出口：OpenAI/Anthropic 协议均走本机 8100 网关
• 虚拟 key 管理：每服务独立 key，真 key 仅存 secret.key
• 文档与报告规范：任务报告按“任务名-日期.md”写入工作区
• 备份与重启规则：改配置先备份，改 systemd/网关后执行对应重载或重启
• 待办跟踪：记录 2026-10-25 的未完成事项与已完成接入

技术栈

使用 / 部署教程

资料未给出独立安装步骤，以下为按文档约定的使用流程。

1. 先读约定：在 workspace C-Windows 开始 AI 会话或任务前，先阅读 AGENTS.md，把机器角色、调用出口、文档和备份规则作为背景约束；除非用户明确要求，不要修改约定条款。

1. 走统一网关：本机调用使用 http://127.0.0.1:8100/v1（OpenAI 协议）或 http://127.0.0.1:8100/v1/messages（Anthropic 协议，DSH 用）。Docker 容器使用 http://172.17.0.1:8100/v1 或对应自定义网络网关。

1. 不要直连外部 API：不要新增直连 api.deepseek.com 的代码；如确需直连，需用户明确要求并在报告中说明原因。

1. 管理 key：每服务使用独立虚拟 key（如 blog、openwebui、aqf、stock、dsh）。真 key 只放在 /opt/ai-gateway/secret.key，不要把任何 key/token/密码写入文档、代码、Git 或聊天。新增服务参考 /opt/ai-gateway/README.md §5.6。

1. 写报告：任务报告写到当前目录，命名 <任务名>-<YYYYMMDD>.md，中文、结论先行，带可复制命令和回滚方法。

1. 改配置先备份：执行 cp -a <file> <file>.bak-<日期>-<说明>。改 systemd 后执行 systemctl daemon-reload；改网关 config 后执行 systemctl restart ai-gateway。

1. 不要手写自动文件：项目进展.md 和 /opt/homelab-git/进展.md 由脚本生成，不要手写内容。项目总览看 全量项目清单-20261024.md，网关手册看 /opt/ai-gateway/README.md。

常见问题