feat: 合并边缘节点运维并完善 Surge 配置安全
迁入通用节点部署工具、离线交付页生成器和共用技能,隔离真实配置与交付产物。统一 Codex 与 Claude Code 开发约定,补充节点迁移与运维文档。 完善 FINAL、策略组引用、输入校验、Surge 字段编码与 AI DNS 例外保护,增加隔离测试和订阅验证工具。 验证:全量类型检查、44 项单测、前端构建、脚本语法、技能入口与凭据隔离检查均通过。
This commit is contained in:
62
docs/AI-COLLABORATION.md
Normal file
62
docs/AI-COLLABORATION.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Codex 与 Claude Code 协作
|
||||
|
||||
项目开发约定以根目录 `AGENTS.md` 为唯一来源。原 `CLAUDE.md` 中的架构、协议适配、前端设计、数据与部署约定已迁入,并根据当前代码补充了初始化、环境变量、AI DNS 与验证说明。
|
||||
|
||||
## 指令入口
|
||||
|
||||
| 工具 | 项目指令 | 项目技能 |
|
||||
|---|---|---|
|
||||
| Codex | 原生读取根目录 `AGENTS.md` | `.agents/skills/<name>/SKILL.md` |
|
||||
| Claude Code | `CLAUDE.md` 中的 `@AGENTS.md` 导入 | `.claude/skills/<name>/SKILL.md` |
|
||||
|
||||
Claude Code v2.1.277 起支持直接读取 `AGENTS.md`,但默认在当前目录或祖先目录已有 `CLAUDE.md`/`CLAUDE.local.md` 时优先读取 Claude 文件。保留 `CLAUDE.md` 的显式导入,使支持导入的旧版本与新版本都能读取同一份规则;无需修改用户全局配置。原生支持不可用的部分旧版本会话也可通过导入加载。
|
||||
|
||||
文件名使用大写、复数的 `AGENTS.md`。不要新增 `agent.md`、`AGENT.md` 或复制一份独立的 Codex 规则。Claude 的 `@path` 是其导入语法,Codex 项目入口本身包含完整规则,无须依赖此语法。
|
||||
|
||||
新开会话时从仓库根目录启动工具。Claude Code 可用 `/memory` 或 `/context` 检查项目指令;Codex 可询问当前项目约定,并用 `/skills` 查看发现的技能。若当前会话未发现新技能,重开会话;不需要额外安装项目技能。全局个人指令与机器设置继续由各工具管理,不写入本仓库。
|
||||
|
||||
## 共用技能
|
||||
|
||||
保留现有 `.claude/skills/` 作为技能源目录,Codex 入口使用相对目录符号链接。Codex 官方支持扫描符号链接指向的技能目录,脚本及评估样例因此也共用一份:
|
||||
|
||||
```text
|
||||
.claude/skills/
|
||||
├── deploy/ # SKILL.md 与 scripts/deploy.sh
|
||||
├── update-db/ # SKILL.md、scripts/api.sh 与 evals/
|
||||
└── edge-node-multi-protocol/ # 节点部署脚本、参考资料与交付模板
|
||||
.agents/skills/
|
||||
├── deploy -> ../../.claude/skills/deploy
|
||||
├── update-db -> ../../.claude/skills/update-db
|
||||
└── edge-node-multi-protocol -> ../../.claude/skills/edge-node-multi-protocol
|
||||
```
|
||||
|
||||
| 任务 | 技能 | Codex 显式调用 | Claude Code 显式调用 |
|
||||
|---|---|---|---|
|
||||
| 部署前端/后端到 LA | `deploy` | `$deploy` | `/deploy` |
|
||||
| 线上数据盘点、导入预览或修改 | `update-db` | `$update-db` | `/update-db` |
|
||||
| 边缘 VPS 部署、重建、协议维护与交付 | `edge-node-multi-protocol` | `$edge-node-multi-protocol` | `/edge-node-multi-protocol` |
|
||||
|
||||
自然语言请求也可以匹配技能。技能提供操作方法,具体外部操作范围仍以用户任务授权为准;阅读部署文档或修改代码不会自动触发上线。
|
||||
|
||||
脚本示例统一保留已有 `.claude/skills/` 路径,两种工具都可在仓库根目录执行。同一脚本也可从 `.agents/skills/` 链接路径执行。新增技能时只写一份源目录,并在 `.agents/skills/` 增加相对链接。
|
||||
|
||||
Git 应保存这些目录链接;在 Windows 上克隆时需要启用符号链接支持,推荐 WSL。若 checkout 将链接变成文本文件,Codex 无法自动发现技能,应恢复目录链接;不要复制出第二份技能。
|
||||
|
||||
## 维护与接续
|
||||
|
||||
- 架构或业务约束改动更新 `AGENTS.md`;较长的专题说明放入 `docs/` 并按任务引用。
|
||||
- 运维流程改动更新 `.claude/skills/<name>/SKILL.md` 及其脚本;`.agents/skills/` 只维护链接。
|
||||
- 节点与应用在本仓库统一维护,节点目录与当前舰队见 `edge-nodes/README.md`。通用工具可入库,真实配置/交付产物放 `edge-nodes/private/` 并用受控备份转交;原 `../edge-nodes/` 仅保留迁移前备份。旧工程指令保存在私有归档中,不作为当前约定。
|
||||
- 普通开发从 `shared` 的类型/校验、`server` 的 API 与 IR、`web` 的状态与页面定位改动。新增客户端先扩展客户端类型与能力矩阵,再增加独立生成器和订阅端点。
|
||||
- 修改规则模板只影响初始化,已有库的配置更新走管理 API;代码部署与数据更新分别执行。
|
||||
- 本地验证按改动范围选择类型检查、单测或构建。临时启动与数据库验证在进程启动前设置临时 `DATA_DIR`,避免触碰真实节点数据。
|
||||
- 交接说明记录已完成改动、验证结果与未完成项;可复用的认识写入项目文件,不依赖某个工具的私有会话记忆。
|
||||
|
||||
## 官方依据
|
||||
|
||||
- [Codex:AGENTS.md 加载规则](https://developers.openai.com/codex/guides/agents-md)
|
||||
- [Codex:技能目录与符号链接支持](https://developers.openai.com/codex/skills)
|
||||
- [Claude Code:AGENTS.md 支持与共用导入](https://code.claude.com/docs/en/memory#agentsmd)
|
||||
- [Claude Code:项目技能](https://code.claude.com/docs/en/skills)
|
||||
|
||||
支持行为核对于 2026-10-03;若工具升级后入口行为变化,按上述官方文档重新核对。
|
||||
Reference in New Issue
Block a user