AGENTS.md git:20261017.9748dbaA

Immutable. This exact content never changes and is served at /api/v1/blob/93e58f02948c24c9.

# ai-vibecode-superpower

本仓库维护可安装的 Codex 与 ZCode 全局配置、agent role 与 standalone skills；两宿主的差异通过 `codex-global-config/` 与 `zcode-global-config/` 目录隔离。项目级约定只在本文件说明；运行时全局行为不在此复制。

## 提示词与文档写作

按 [OpenAI Model Guidance](https://developers.openai.com/api/docs/guides/latest-model#prompting-best-practices) 维护提示词与文档：

1. **先写意图与结果**：给出目标、相关上下文、硬约束、授权边界、成功标准和必要输出格式；让模型自行选择正常步骤，只把会实质改变结果的歧义上升为问题。
2. **保持精简**：每条规则只写一次，role、模板和说明链接到权威来源而不重复；工具描述简短、精确；示例仅用于表达产品要求或修复已验证的问题。
3. **以可观察结果写文档**：结论在前，随后给出证据、重要限制与下一步；区分事实和判断，说明目标、非目标、可见行为与验证方式。
4. **明确长度与语气**：短答复说明必须保留和可省略的信息，不使用泛泛的“简短”；直接回答，用户报告问题时先回应具体问题，省略泛泛表扬、安慰和签名。
5. **用评估迭代**：基于代表性任务，每次只增删一组提示词、示例或工具，再比较任务成功、完整性、证据、token、延迟与成本。

## README 定位

1. `README.md` 是使用者手册：只说明用途、适用场景、简明工作流、安装入口和可选能力。
2. 不在 README 重复 role 路由、模型选择、消息字段、权限边界、并发限制、配置合并或安装器实现细节。
3. 技术规则只在其权威来源维护：项目文档边界在本文件，工作流在 `codex-global-config/skills/orchestrate-model-workflow/SKILL.md` 与 `zcode-global-config/skills/orchestrate-model-workflow/SKILL.md`，role 边界在 `codex-global-config/agents/ai-vibecode-superpower/` 与 `zcode-global-config/agents/ai-vibecode-superpower/`，安装行为在安装脚本。README 仅在确有必要时链接这些来源。

## 权威来源

- 共享平台文档与工具无关 skills：`shared/`（`docs/system/`、`agent-toolchain`、`project-doc-planner`、`visual-aesthetics`），由两个安装器共同安装。
- Codex 全局行为规范：`codex-global-config/AGENTS.md`；安装后对应用户级 Codex home 中的 `AGENTS.md`。ZCode 对应 `zcode-global-config/AGENTS.md` 与用户级 ZCode home（`~/.zcode`）。
- 工作流路由、交接与验收：`codex-global-config/skills/orchestrate-model-workflow/SKILL.md`（Codex 变体）与 `zcode-global-config/skills/orchestrate-model-workflow/SKILL.md`（ZCode 变体）。
- role 本地权限与输出边界：`codex-global-config/agents/ai-vibecode-superpower/`（11 个 toml role：luna / sol / astra 三型，sol 含 gpt-6.1 主力与 gpt-6 同型回退）与 `zcode-global-config/agents/ai-vibecode-superpower/`（5 个 md agent）。角色命名统一为 `模型_版本_类型_思考档`（如 `glm_5.3_flash_low`、`gpt_6_astra_max`），同模型同档位冲突时追加职责后缀。md agent 的 frontmatter `model` 必须写 ZCode Picker 值 `providerId/modelId`（如 `"account:bigmodel-individual-coding-plan/GLM-5.3-Flash"`，provider 段随实际登录的 Coding Plan 账号走），`thoughtLevel` 单独成键；裸模型名会被 ZCode 静默忽略并回退到父会话模型。
- 安装与合并逻辑：`install.ps1`、`install.sh`（每平台一个安装器，交互选择客户端或以 `-Client`/位置参数指定）；不要直接编辑已安装的全局副本作为最终修改。ZCode 的 md agent 按 manifest 平铺安装到 `~/.zcode/agents/` 顶层（新版宿主只扫描顶层，子目录不参与发现）；旧版安装的 `agents/ai-vibecode-superpower/` 子目录仅在内容与 manifest 完全一致时随安装备份移除。

## 修改与验证

1. 修改全局行为、skill 或 role 时，先改本仓库中的权威来源；role 内容变更同时更新其 SHA-256 manifest。
2. 只有用户要求部署时，运行对应平台的 `install` 脚本并选择目标客户端，核对已安装文件与源文件一致。
3. 保留实际错误和未验证项；不得用未证明兼容的 fallback 隐藏问题。