CloudBase-AI-Toolkit: Instructions file for Codex

# 需求文档

## 介绍

需求描述

## 需求

### 需求 1 - 需求名称

**用户故事：** 用户故事内容

#### 验收标准

1. 采用 ERAS 描述的子句 While <可选前置条件>, when <可选触发器>, the <系统名称> shall <系统响应>，例如 When 选择"静音"时，笔记本电脑应当抑制所有音频输出。
2. ...
...

1. 技术方案设计：对于需要 spec 的需求，在完成需求设计之后，你会根据当前的技术架构和前面确认好的需求，进行技术方案设计，保存在 specs/spec_name/design.md 中，精简但是能够准确描述技术架构（例如架构、技术栈、技术选型、数据库/接口设计、测试策略、安全性），必要时可以用 mermaid 来绘图，跟我确认清楚后，才进入下阶段。对于不需要 spec 的小需求，可以直接在对话中给出精简方案并继续执行。

2. 任务拆分：对于需要 spec 的需求，在完成技术方案设计后，你会根据需求文档和技术方案，细化具体要做的事情，保存在 specs/spec_name/tasks.md 中，跟我确认清楚后，才开始正式执行任务，同时更新任务状态。对于不需要 spec 的小需求，可以直接给出精简任务说明或直接执行。

   注：specs/ 已加入 .gitignore，spec 文档只写在本地、不要 git add 到公开仓库（含内部信息，完整历史归档在私有仓库 cloudbase-mcp-specs-archive）。

格式如下

# 实施计划

- [ ] 1. 任务信息
  - 具体要做的事情
  - ...
  - _需求: 相关的需求点的编号

<project_rules>

1. 项目结构

   • doc 存放对外的文档
   • mcp 核心的 mcp package
   • config 用来给 AI IDE 提供的规则和 mcp 预设配置
   • tests 自动化测试
   • skills 项目级 skills 源目录
   • specs 需求/设计/任务文档（本地目录，不提交到公开仓库。含内部信息，仅保留 plugin-marketplace-listing/ 与 npm-supply-chain-security-hardening/ 两个被代码或规范依赖的子目录；完整历史归档在私有仓库 cloudbase-mcp-specs-archive）

2. AGENTS 文件约定

   • AGENTS.md 为项目及子目录的唯一可信源
   • CLAUDE.md、CODEBUDDY.md 均为指向 AGENTS.md 的软链
   • 新增子目录时，只需创建 AGENTS.md，用软链补齐 CLAUDE.md

3. Skills & Rules 目录约定

   • .agents/skills 为 skills 的唯一可信源，.codebuddy/skills、.claude/skills 软链至此
   • .agents/rules 为 rules 的唯一可信源（尚未创建时以 .agents/rules 为目标）
   • 新增 skills 请直接添加到 skills/ 目录，.agents/skills/ 下的软链会自动关联
   • 如果使用 npx skills 命令添加 skills 时保留 Universal 选项，不用重复添加 claude 和 codebuddy 选项
   • 某个目录中只要有 AGENTS.md、CLAUDE.md 和 .agents/skills、.claude/skills 中的任意一个，就需要自动补齐

4. 项目子目录规则

   • dsh-plugin/ 已有自己的 AGENTS.md（源）+ CLAUDE.md、CODEBUDDY.md 软链；新增子包照此补齐
   • mcp/ 不设自己的 AGENTS.md —— mcp 包的约定已全部写在根文件里（mcp_tool_schema_rules、add_aiide、ide_mcp_upgrade、cloud_api_backend_rules 等段都是针对它的），该目录下不得出现任何 IDE 兼容产物 </project_rules>

• 真源在仓库 plugins/experts/<expert-name>/（一个专家一个子目录，版本控制）；与对外发布目录 plugin/（CodeBuddy plugin）区分
• WorkBuddy 专家目录 ~/.workbuddy/plugins/marketplaces/my-experts/plugins/ 是同步产物（build output），禁止手改（会被覆盖）；修改一律走"改仓库源码 → 同步命令"
• 同步：npm run experts:sync [expert-name]（脚本 scripts/sync-experts.mjs：rsync --delete 镜像 → validate_expert.py → register_expert.py）；expert-manager 脚本在 WorkBuddy app bundle 内，路径可用 EXPERT_MANAGER_SCRIPTS_DIR 覆盖
• 内容原则：精简有效、引用为主——Agent MD 只留角色/SOP/铁律/路由，领域知识引用运行时官方 skills，不复制进包防漂移；踩坑经验官方 skill 未覆盖的才留包内
• 后续加新专家 = 在 plugins/experts/ 建目录（手工建骨架，init_expert.py 强制写 my-experts 目录与仓库真源冲突）→ npm run experts:sync；删除专家 = 删源码目录 → 全量 npm run experts:sync（脚本自动清理 my-experts 孤儿产物）
• plugin.json 的 displayDescription 限制 40-50 字，超长会校验 warning；tags 必须恰好 3 个；quickPrompts 必须恰好 3 条；defaultInitPrompt 各语言须与 quickPrompts[0] 完全一致
• 头像统一 512×512 PNG，放 avatars/<expert-name>.png，与 plugin.json 的 avatar 字段同名同路径

<internal_dirs>