codex-mcp: Instructions file for Codex

AGENTS.md

项目身份

• 本仓库是面向 ChatGPT 的本机 coding MCP，核心由本机 Controller、MCP Runtime、项目注册/会话绑定、OAuth/公网入口和 Web Console 组成。
• Web Console 是本机控制面，不是独立 SaaS：主要入口为 src/ui/console/**，技术栈固定为 Vue 3 + TypeScript + Element Plus + Vite。
• Controller 与 CLI 应尽量复用 src/control/services.ts 等共享 service；除纯 UI 状态外，不在 Web 或 CLI 复制一套业务规则。
• 优先最小、可运行、可验证的实现；不要为了统一风格、提前抽象或顺手清技术债扩大 diff。
• 不得以“个人工具”为理由削弱已有的 OAuth、CSRF、Origin、SSRF、路径隔离、Cloudflare 所有权或持久化事务边界。

执行协议

开始修改前按顺序执行：

1. 读取当前路径生效的 AGENTS.md。
2. 检查 git status，区分已有脏文件和本任务改动；不要碰与任务无关的脏文件。
3. 确认真正生效的 CLI → Controller → service → Runtime / Tunnel 调用链，以及 Web route → component → API → service 调用链；存在但没有入口或调用方的旧文件不能作为当前事实。
4. 先检查用户需求是否存在错误前提、逻辑跳跃或信息缺失；区分事实、推测和主观判断，发现冲突直接指出。
5. 涉及外部系统时确认所有权与回滚边界：Cloudflare DNS/Tunnel、OAuth client、文件系统、项目状态都不能靠名称或猜测直接覆盖/删除。
6. 定义最小必要修改范围和能证明结果的最低成本验证方式，再开始修改。
7. 修改过程中如果真实测试暴露新的根因，先补行为回归，再修实现；不要顺着现有代码写只会通过的测试。

生命周期不变量

• project add/remove 只改变项目注册状态，不隐式启动 Runtime。
• open 只确保 Controller / Web Console 可用，不启动 Runtime。
• start 启动 Runtime，并使用显式模式或已持久化的运行偏好；项目注册应先于 Runtime 前置校验完成。
• stop 只停止 Runtime/Tunnel，Controller 与 Web Console 保持在线。
• shutdown 才完全关闭 Runtime 与 Controller。
• 配置状态、持久化状态和当前运行状态是不同概念；UI/CLI 不得把其中一个伪装成另一个。
• Runtime、Tunnel、Controller 的长生命周期操作必须使用各自真实 deadline；探活 timeout 不能复用于启动/停止操作。

Web Console 架构

• 页面组件负责页面编排和交互状态；网络请求统一通过 src/ui/console/api.ts，页面不得自行拼 Controller URL、CSRF 或 fetch 基础设施。
• Web 只调用 Controller API；业务语义放到共享 service，确保 CLI 与 Web 对同一操作具有一致行为。
• App.vue 负责全局导航、跨页面状态和生命周期；View/Component 保持局部职责，不把所有逻辑重新堆回根组件。
• 外部 CLI、Runtime 或配置文件可能在页面打开期间改变状态；Web 必须有明确的状态同步策略，不能只依赖用户手动刷新。
• 异步请求、EventSource、timer、AbortController、原生文件选择等由谁创建就由谁 cleanup；组件卸载、Dialog 关闭或 Controller 替换后不得留下 owner 不明的后台任务。
• 异步旧结果不得覆盖更新后的页面状态；轮询/刷新要防并发竞态，长操作结束后再解锁相关 UI。
• 用户未保存的本地表单编辑不能被后台状态刷新静默覆盖；需要同步外部变化时先区分 server state 与 draft state。

Vue / Element Plus

• 使用 Vue Composition API 和明确 TypeScript 类型；当前规模不引入 Pinia，除非出现真实跨页面状态复杂度证明需要。
• Element Plus 使用当前按需导入方案；禁止恢复 app.use(ElementPlus) 或 element-plus/dist/index.css 全量导入。
• 通用 Button、Dialog、Drawer、Table、Tabs、Form、Switch、Message、MessageBox 等优先 Element Plus，不再自建一套通用 UI primitives。
• 所有 Dialog/Drawer 必须有明确取消或关闭路径；异步提交期间防重复触发，同时允许用户理解当前正在做什么。
• 面向用户的默认文案使用中文；内部 PID、revision、Tunnel ID、命令等技术信息只在需要的位置展示，避免首页堆内部术语。
• 操作名称必须描述真实副作用，例如“生成并设置密码”不能写成看起来只会生成。