Skip to content

AGENTS.md

Latest commit

 

History

History
141 lines (126 loc) · 15.1 KB

AGENTS.md

File metadata and controls

141 lines (126 loc) · 15.1 KB

AGENTS 执行规范（精简可执行版）

0. 路径规范（不可删）

以下目录结构为长期约束，后续修改 AGENTS.md 时不得删除，只能增补：

.
├── .codex/            # Codex 项目级配置：subagent、项目运行参数等
│   ├── config.toml
│   └── agents/        # 项目级 Codex custom agents
├── AGENTS.md          # 行为规则，可按任务优化但需保留路径规范
└── docs-linhay/       # 项目文档系统目录：开发计划、需求文档、技术文档等
    ├── spaces/        # 以 feature / topic / milestone 为单位的工作空间根目录
    │   └── <space-key>/
    │       ├── README.md      # 当前 space 的需求背景、目标、范围、验收标准
    │       ├── plans/         # 开发计划、迭代规划、里程碑
    │       └── screenshots/   # 截图，按日期/模块分层存放
    ├── dev/          # 研发文档（架构、技术方案、测试策略、数据字典等）
    ├── memory/       # 记忆系统（MEMORY.md + 每日日志）
    ├── references/   # 参考项目、外部资料归档
    └── scripts/      # 自动化脚本及其说明文档

补充约束：

  1. spaces 为正式目录名，后续所有文档落位和引用都以该路径为准。
  2. <space-key> 采用可追踪的英文 slug，优先使用 <YYYYMMDD>-<topic> 或稳定功能名，禁止空格、中文、latest、final。
  3. 每个 space 的入口文档固定为 README.md。
  4. feature 开发用的 Git worktree 不放在仓库目录内，统一放在主仓库同级目录 ../GetTokens-worktrees/。
  5. 单个 feature worktree 的推荐路径为 ../GetTokens-worktrees/<space-key>/；默认与对应 space 共享同一个 <space-key>。
  6. worktree 是临时执行环境，space 是长期文档资产；需求完成后可删除 worktree，不得删除对应 space 历史。
  7. 单个 space 的单期设计稿默认只保留一个 HTML 文件；若存在多稿对比，也必须收敛在同一个 HTML 文件内，不再为同一期拆分多个 option-*.html。

1. 全局原则

  1. BDD + TDD 必须先行：先场景与验收标准，再失败测试，再实现。
  2. 全程中文沟通。
  3. 小步提交、可回归验证，避免大块不可控改动。
  4. E2E 场景覆盖核心功能，单元测试覆盖边界条件。
  5. 文档与记忆同步更新，保持信息一致性。
  6. 任何改动都要考虑对后续维护者的可理解性和可操作性。
  7. 涉及 Web / 前端体验优化时，默认由 Gemini 主导前端实现；Codex 负责业务逻辑、接口契约、状态流转、测试门禁、回归验收与最终集成。
  8. 前端改动若影响后端接口、领域模型或关键交互闭环，必须先由 Codex 明确边界，再交给 Gemini 落地，避免只改视觉不改业务完成度。
  9. 当一次会话中出现“有用且重复出现”的行为模式、排障路径或交付动作时，必须先识别复用边界，再优先新增或更新项目级 skills；只有当规则已经上升为 repo-wide、长期稳定的约束时，才同步更新 AGENTS.md。
  10. 当用户明确说“整理”且语境指向刚完成的一轮工作会话时，默认触发一次会话沉淀流程：先按 gettokens-session-skill-distill 提炼可复用模式，再按是否 repo-wide 决定是否同步更新 AGENTS.md、docs-linhay/dev/、docs-linhay/memory/。
  11. 多份独立需求稿并行推进时，默认按“一个需求单元一个 space，必要时再配一个同 key 的 branch 与 worktree”组织，不按个人姓名或临时阶段单独命名工作目录。
  12. 当用户明确要求“由 subagent 去做、主控 agent 负责监督”时，主控 agent 必须承担需求边界、任务拆分、集成、验收、文档与最终完成判断，不得在“代码已改完”但截图、实机验证、文档写回等验收环节仍未完成时提前停止。
  13. 当某个 space 的需求施工结束并进入整理期时，默认执行一次行为保持的收尾整理：识别大文件和大数据结构，优先按稳定边界拆分文件；同步提取可复用流程到项目级 skills，仅把 repo-wide 且长期稳定的规则写入 AGENTS.md；最后更新 space、dev 文档与 memory。
  14. 本地 Web / Wails 预览验收默认使用无头浏览器、DOM 断言和文件截图；除非用户明确要求可见窗口，否则不得把 Playwright、Chrome 或其他浏览器验收窗口打开到用户当前激活显示器。确需可见窗口时必须先询问，或放到非激活副屏。
  15. 通用看板产品线按固定节奏推进：新建 space -> 设计需求 -> 技术细节补充 -> 回到需求调整 -> 调整设计系统的稿子 -> 执行开发 -> 冒烟测试 -> 交付用户测试。
  16. sidecar 是 GetTokens 运行态自治层。账号选择、rate-limit、route guard、live sessions、usage attribution、system proxy、Codex WebSocket 等热路径状态优先在 CLIProxyAPI#gettokens/sidecar 内闭环，不通过前端或 Wails 临时补偿来伪造 sidecar 已处理状态。
  17. 从账号与凭证 SQLite 统一存储版本开始，GetTokens sidecar 不再跟随 CLIProxyAPI 上游做合并式同步。上游提交和功能只能作为参考输入；需要的能力必须在 GetTokens sidecar 边界内重新设计、实现、补窄测试并重建 sidecar。management API 可以按 GetTokens 需求破坏性调整，不为了上游兼容保留旧合约。
  18. GetTokens 是 macOS/Wails 桌面工作台产品，默认不做移动端适配、移动端截图或 375/390px 宽度验收。前端与视觉改动默认按桌面窗口、Wails 容器和可用的桌面浏览器预览验收；只有用户在当前需求中明确提出移动端目标时，才增加移动端布局与截图门禁。
  19. 项目级 Codex subagent 配置统一放在 .codex/agents/，默认命名为 gettokens_*；除非正在验证模型路由能力，否则 agent 默认继承父会话模型，只用职责、sandbox 和 reasoning effort 区分任务面。
  20. 主控 agent 可根据任务判断自主新增、删除或修改 .codex/agents/*.toml，不需要逐次请求授权；但必须说明判断依据，验证 TOML 可解析，并更新 docs-linhay/dev/20260530-codex-project-subagents.md 与 memory。
  21. 工作台内详情类或调试类 modal 默认必须使用覆盖整个应用窗口视口（包括 sidebar 区域）的遮罩层，面板四周保留可见遮罩与投影间距，并具备可恢复的独立 hash 路由。打开 modal 时写入 detail=<id> 或 modal=<route>，关闭时只移除对应标记；全局 hash canonicalizer 不得丢弃仍属于当前 frame/workspace 的 modal/detail 参数。
  22. 上下游自身限制不由 GetTokens 默认兜底：若根因属于 Codex CLI / Codex upstream 的协议行为、请求体限制或服务端限制，而非 GetTokens sidecar 引入的重复、放大、错误转换或本地限制，默认只做定位、证据保留和规避建议；只有确认是 GetTokens 转发层自身 bug，或用户明确授权做兼容层，才进入 GetTokens 侧实现。
  23. 未经用户明确授权，不得触碰正式版 GetTokens：修复与验证默认只在 dev 环境、本仓库构建产物或明确指定的测试环境中进行；禁止擅自修改 /Applications/GetTokens.app 正式版二进制、重启/kill 正式版进程、替换正式版 sidecar 或改动正式版配置。
  24. 正式版数据可拷贝到 dev 环境用于复现问题：允许从 /Users/linhey/.config/gettokens/ 拷贝 SQLite 数据库、配置文件等数据到 /Users/linhey/.config/gettokens-dev/ 进行测试，但必须先在 dev 目录备份原有数据，验证完成后恢复。

2. 标准工作流（必须）

  1. 明确需求边界与验收条件。
  2. 先补测试并确认失败（红灯）。
  3. 最小实现让测试通过（绿灯）。
  4. 必要重构并保持测试通过。
  5. 更新相关文档与记忆。
  6. 若本次任务提炼出可复用的项目动作、流程或知识边界，新增或更新对应 skills；若同时形成长期稳定规则，再更新 AGENTS.md。
  7. 若用户以“整理”作为收尾指令，且本轮存在稳定可复用模式，不需要额外追问是否沉淀，直接进入 skills / AGENTS / docs / memory 的整理流程。
  8. 若某个需求将进入并行开发、多日实现或与其他需求同时切换，先补齐对应 space，再创建同 key 的 branch / worktree。
  9. 若需求采用 subagent 交付，标准完成顺序必须覆盖：需求边界确认、subagent 分工、主控集成、自动化验证、Wails/桌面验收（如适用）、截图或其他验收产物、文档与记忆写回；未跑完这一整链，不得宣称需求完成。
  10. 通用看板产品线每轮都必须先更新对应 space 的需求与验收，再补技术细节；技术约束反推需求后，需要回到 space 调整需求，再进入设计系统稿、开发、冒烟和用户测试。

3. 测试门禁（必须）

  1. 任何功能改动都要有对应测试（新增或更新）。
  2. 未运行测试时必须明确说明原因与风险。
  3. 禁止“只改代码不验证”。
  4. 纯文档或治理规则调整若无可执行测试，至少要完成结构自检、路径校对与引用校对，并在交付说明中明确写明“未运行自动化测试”的原因。

4. 文档系统规则（docs-linhay）

docs-linhay/ 是项目文档系统目录，按类型分文件夹：

  1. docs-linhay/spaces/<space-key>/README.md：单个需求空间的背景、目标、范围、验收标准、相关链接。
  2. docs-linhay/spaces/<space-key>/plans/：该需求空间下的开发计划、迭代规划、里程碑。
  3. docs-linhay/spaces/<space-key>/screenshots/：该需求空间下的截图归档。
  4. docs-linhay/dev/：研发文档、技术方案、治理说明。
  5. docs-linhay/memory/：记忆系统（MEMORY.md + 每日日志 YYYY-MM-DD.md）。
  6. docs-linhay/references/：参考项目、外部资料归档。
  7. docs-linhay/scripts/：自动化脚本及其说明文档。

Git worktree 治理：

  1. space 负责需求背景、计划、截图和验收；worktree 只负责该需求的代码执行上下文。
  2. 默认映射为：space = docs-linhay/spaces/<space-key>/、branch = feat/<space-key>、worktree = ../GetTokens-worktrees/<space-key>/。
  3. 只讨论、不落代码的需求稿只建 space，不建 worktree。
  4. 一次性小修或当天即可完成的短改动，可直接在主工作区开短分支，不强制建 worktree。
  5. 会并行推进、会持续多天、会频繁切换上下文的需求，必须使用独立 worktree。
  6. release、打包、一次性验证类短命工作区可继续放在 /private/tmp/，但常规 feature worktree 不得放在 /tmp。
  7. 禁止在主仓库目录内嵌套创建 feature worktree，避免污染搜索、索引和脚本扫描范围。
  8. 合并完成后删除对应 worktree，保留 space 文档、截图和计划历史。

设计稿治理：

  1. 设计稿 HTML 默认落在对应 space 根目录，作为该期视觉/交互方案的唯一入口。
  2. 单个 space 的单期设计稿只保留一个 HTML 文件，文件名应语义化且可追踪，例如 design-preview.html、usage-dashboard-design-v01.html。
  3. 同一期内若需要展示多方案对比、多个状态或多个区域稿，统一放在同一个 HTML 文件中，用分节、锚点或标签页组织，不再拆成多个平行 HTML 文件。
  4. 只有跨期迭代时才允许新增下一版 HTML，例如从 *-v01.html 演进到 *-v02.html；同一期内禁止出现 option-a/b/c 平行文件。
  5. 既有多 HTML 设计稿视为历史遗留；后续新增或重构时按本规则收敛，不要求本次治理整理顺手迁移所有旧稿。

文档落位硬约束：

  1. 需求变更先写对应 space，再改代码。
  2. 技术方案和治理说明放 docs-linhay/dev/。
  3. 截图、计划材料必须跟着对应 space 走。
  4. 外部参考资料统一归档到 docs-linhay/references/。
  5. 完整源码型本地参考项目默认不进入 git；docs-linhay/references/ 只提交根部 Markdown 索引、调研摘要和必要的小型资料，参考项目源码目录由 .gitignore 忽略。既有已跟踪参考目录视为历史遗留，后续新增参考项目必须遵循“不提交源码目录，只提交调研结论”的规则。

项目级 skills：

  1. 涉及 space 创建、命名、README 模板或截图归档时，优先使用 gettokens-ops-governance。
  2. 涉及文档写回或 memory 写回时，优先使用 gettokens-ops-governance。
  3. 涉及 AGENTS 级长期治理规则时，优先使用 gettokens-ops-governance；若用户明确说“整理”，同时使用 gettokens-session-skill-distill。
  4. 涉及账号池、quota、视觉系统、前端调试归因或 CLIProxyAPI fork 维护时，优先使用 gettokens-domain-engineering。
  5. 涉及 Codex 账号列表、请求顺序、路由探测、OAuth/openai-compatible 模型映射时，优先使用 gettokens-codex-account-list。
  6. 涉及“主控 agent 监督、subagent 实做、直到完整需求闭环才停止”的执行模式时，优先使用 gettokens-ops-governance 中的 Subagent Delivery Loop。
  7. 若用户希望用显式 skill 名称触发该模式，使用 gettokens-subagent-supervision；它是监督交付模式的轻量触发入口。
  8. 涉及 Codex Skills / MCP Servers、[[skills.config]]、tk://github.com / tk://gitlab.com Skill source、~/.codex/config.toml MCP 解析与保存时，优先使用 gettokens-codex-extensions-management。
  9. 涉及项目级 Codex custom agents、.codex/config.toml、.codex/agents/*.toml 或 subagent 任务分工配置时，优先参考 docs-linhay/dev/20260530-codex-project-subagents.md。
  10. 涉及项目级 Codex subagent 的新增、删除、合并、拆分、验证或生命周期治理时，优先使用 gettokens-subagent-lifecycle。

5. 记忆系统规则（必须）

5.1 Writeback（写回）

出现以下情况必须写入记忆：关键决策、行动项、偏好变化、里程碑、风险结论。

  1. 写入 docs-linhay/memory/YYYY-MM-DD.md
  2. 每周合并到 docs-linhay/memory/MEMORY.md（只保留稳定高价值信息）

6. 文档工具（推荐）

  1. 新建 space 时优先使用 docs-linhay/scripts/create-space.sh <space-key>。
  2. 提交前或调整治理规则后，运行 docs-linhay/scripts/check-docs.sh 做结构校验。
  3. 新建 feature worktree 时，默认使用 git worktree add ../GetTokens-worktrees/<space-key> -b feat/<space-key> master；若当前集成分支不是 master，以当轮基线分支替换末尾参数。
  4. 采用 subagent 交付的需求，主控 agent 收尾前默认补做一次 DoD 自检：测试、桌面验收、截图、文档、memory、必要时 check-docs.sh。

7. 完成定义（DoD）

  1. 验收场景满足。
  2. 相关测试通过，或已说明阻塞、未测原因与风险。
  3. 文档已更新到正确目录。
  4. 有意义变更已写入记忆并可追溯。
  5. 若本次工作产生了可复用且重复出现的行为模式，已完成对应 skills / AGENTS.md 的新增或更新，或已明确说明为何暂不沉淀。