isrvd: Instructions file for Codex

AGENTS.md — isrvd Agent 操作指南

本文件是 isrvd 仓库根规范入口。子目录可有专项 AGENTS.md，目标：可执行、可验证、低歧义。

---

1) 指令优先级

冲突时：用户明确需求 → 安全稳定性 → 本规范 → 现有代码风格 无法消解时：不泄露敏感信息、不引入破坏性变更、不修改需求范围外逻辑

---

2) 工作流

• 先理解再改动：定位模块、调用链、类型与边界，不基于猜测修改
• 小步提交：最小可行改动，每步可解释"为什么改、改了什么、如何验证"
• 变更后验证：执行相关静态检查；无法完整验证时说明风险
• 同步更新文档：外部可观察的 API、配置、数据结构、工作流或脚本用法发生变化时同步文档；纯重构、格式整理和内部并发封装无需制造无意义文档差异

---

3) 项目架构

实际依赖方向

仓库不是单一线性依赖链，当前 import 边界为：

cmd/server ───────────────→ config + internal/registry + internal/server
config ───────────────────→ pkgs/cstore
internal/registry ────────→ config + pkgs/{apisix,caddy,docker,swarm}
internal/service/* ───────→ config / internal/registry / pkgs/*
internal/service/{docker,webssh} → internal/service/shell（终端桥接复用）
internal/server ──────────→ config + internal/registry + internal/service/* + pkgs/* + public

• pkgs/：底层客户端、存储适配和 SDK 类型转换；不依赖 internal/
• internal/registry/：根据 config 创建 APISIX、Caddy、Docker、Swarm 底层实例
• internal/service/：业务组合、参数校验、稳定 API 类型转换；不得依赖 internal/server
• internal/server/：Gin HTTP/WebSocket 入口、路由索引、中间件、服务生命周期与响应封装
• cmd/server/：仅执行 config.Init → registry.Init → server.StartApp

禁止

• pkgs/ 依赖 internal/
• handler 中堆叠业务逻辑
• service/handler 直接从配置创建外部客户端；外部客户端统一由 registry 初始化并注入/引用

内聚与耦合

• 同领域功能聚合同包（pkgs/docker/、pkgs/swarm/、pkgs/caddy/），类型就近定义，不集中 types.go
• 层间通过接口或注入解耦；前端全局状态通过 Pinia usePortal() 聚合访问
• 判定：改一个功能只需改一处；若需同时改多个包同名函数，说明内聚不足

---

4) 代码变更同步文档规范

外部行为变化时必须同步相关说明文档，确保文档与代码一致。仅移动代码、抽取辅助函数、修复缩进、返回对象快照化等不改变外部契约的修改，不要求更新 API 文档。

适用范围

所有涉及以下外部可观察变更的场景：

• 新增/修改/删除 API 路由或参数
• 新增/修改/删除 数据结构（Request/Response 字段）
• 新增/修改/删除 业务逻辑或工作流
• 新增/修改/删除 配置项或环境变量
• 新增/修改/删除 Shell 脚本中的命令或参数

Docs 文件结构

docs/
├── SKILL.md                      ← 索引 + 决策树 + 常见工作流
├── scripts/
│   ├── api.sh                    ← Bash API 调用封装
│   ├── api.js                    ← JavaScript API 调用封装
│   └── api.py                    ← Python API 调用封装
└── references/
    ├── docker/{containers,images,networks,volumes,registries}.md
    ├── swarm/{info,services,tasks}.md
    ├── apisix/{routes,upstreams,consumers,ssl}.md
    ├── caddy/{routes,certs,config,basic-auth}.md
    ├── system/{config,account,filer,cron,ssh}.md
    ├── ssh/{hosts,sftp}.md
    ├── agent.md
    ├── overview.md
    ├── compose.md
    ├── shell.md
    └── ...