AGENTS.md · TencentCloudBase/CloudBase-AI-Toolkit

Sections

1. WorkBuddy 专家包源码约定
2. 本地内部目录的存放、同步与获取
3. 发版强制项（防漂移）
4. 关键约束

First lines (shown under the repo's MIT license)

---
alwaysApply: true
---

<workflow>
1. 每当我输入新的需求的时候，为了规范需求质量和验收标准，你首先会搞清楚问题和需求
2. 需求评估：先根据需求大小、影响范围、复杂度和风险判断是否需要走完整 spec 流程。对于跨模块、中大型、高风险、涉及较多协作或验收边界不清晰的需求，必须先补齐 spec；对于小型、低风险、边界清晰的改动，不强制要求产出 spec，但仍需先明确目标、范围和验收标准。
3. 需求文档和验收标准设计：如果判断需要 spec，则先完成需求设计，按照 EARS 简易需求语法方法来描述，保存在 `specs/spec_name/requirements.md` 中，跟我进行确认，最终确认清楚后，需求定稿，参考格式如下

```markdown
# 需求文档

## 介绍

需求描述

## 需求

### 需求 1 - 需求名称

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

#### 验收标准

1. 采用 ERAS 描述的子句 While <可选前置条件>, when <可选触发器>, the <系统名称> shall <系统响应>，例如 When 选择"静音"时，笔记本电脑应当抑制所有音频输出。
2. ...
...
```
4. 技术方案设计：对于需要 spec 的需求，在完成需求设计之后，你会根据当前的技术架构和前面确认好的需求，进行技术方案设计，保存在 `specs/spec_name/design.md` 中，精简但是能够准确描述技术架构（例如架构、技术栈、技术选型、数据库/接口设计、测试策略、安全性），必要时可以用 mermaid 来绘图，跟我确认清楚后，才进入下阶段。对于不需要 spec 的小需求，可以直接在对话中给出精简方案并继续执行。
5. 任务拆分：对于需要 spec 的需求，在完成技术方案设计后，你会根据需求文档和技术方案，细化具体要做的事情，保存在 `specs/spec_name/tasks.md` 中，跟我确认清楚后，才开始正式执行任务，同时更新任务状态。对于不需要 spec 的小需求，可以直接给出精简任务说明或直接执行。

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

格式如下

``` markdown
# 实施计划

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

```
</workflow>


<project_rules>
1. 项目结构
   - doc 存放对外的文档
   - mcp 核心的 mcp package
   - config 用来给 AI IDE 提供的规则和 mcp 预设配置
   - tests 自动化测试
   - skills 项目级 skills 源目录
   - specs 需求/设计/任务文档（**本地目录，不提交到公开仓库**，无例外子目录。含内部信息，完整历史归档在私有仓库 `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>

<experts>
## WorkBuddy 专家包源码约定

- **真源**在仓库 `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` 字段同名同路径
</experts>

<internal_dirs>
## 本地内部目录的存放、同步与获取

这些目录**都不提交到公开仓库**，只在本地维护：

| 目录 | 内容 | 为什么不入库 |
| --- | --- | --- |
| `specs/` | 规格 / 设计 / 审视报告 | 含内部任务 ID、审视报告、评测/归因上下文 |
| `.workbuddy/` | IDE 本地状态：AI 每日记忆、plans、expert 会话历史 | 类比 `.idea/` / `.vscode/`，本就不该进版本控制；记忆里带内部任务 ID 与未公开决策 |
| `.cursor/plans/` | Cursor 的计划文件 | IDE 本地状态；正文里带本机绝对路径与未公开的计划内容 |
| `.codebuddy/` | IDE 本地状态：`automations/`、`artifacts/`、`settings.local.json` | 同上；`artifacts/` 里是内部审视与改稿提案 |

`specs/` 全量忽略、无例外：`plugin-marketplace-listing/` 是渠道 BD 台账，2026-10-21 整体退出；`npm-supply-chain-security-hardening/` 的指南已于 2026-10-27 并入本文件 `<supply_chain_security>` 段，spec 目录随之删除。`.workbuddy/` 全量忽略。`.codebuddy/` 里只有 `skills/`（指向 `.agents/skills` 的软链投影，与 `.claude/skills` 对称）入库。`.cursor/rules/` 是项目规范，同样有意保留。

`docs/` 走的是相反的白名单：只放对外文档（`enterprise-auth-with-feishu.md`、`research-codex-plugin-enterprise-auth.md`），其余一律当内部工作件——门禁报告、platform-kit spec 与能力对齐表都在此列。`dsh-plugin/community/SUBMISSION.md`、`dsh-plugin/scripts/t9-results.md`、`mcp/scripts/wxide-mcp-e2e-test.md` 三个开发过程记录同理：本地保留、不入库。这几类的门禁由 `scripts/git-guard-internal.sh` 与 CI 的 Internal Docs Guard 同时把关。

**写**：新 spec 照旧写在本仓库 `specs/<name>/{requirements,design,tasks}.md`，只是不要 `git add`。`.workbuddy/`、`.cursor/plans/`、`.codebuddy/` 由 IDE 自行维护，不用管。

### 切分支 / merge 后目录变空是预期行为

这些目录不再被 git 跟踪，**从旧分支切到已移除它们的分支（或 merge 这类分支）时，git 会把工作区里的文件删掉**。这不是数据丢失：`specs/` 与 `.workbuddy/` 的真源在私有归档仓里，`.cursor/plans/` 与 `.codebuddy/` 的内容仍在 git 历史里（移出前已提交过那个版本）。

后两个目录**不接归档同步**（下节的 `npm run internal:*` 只管 `specs/` 与 `.workbuddy/`）——它们是纯 IDE 状态，切分支前想留内容就自己拷走。

- 提交时由 `pre-commit` 自动恢复一次（`lefthook.yml` 的 `internal-restore`）——本机 `post-checkout` / `post-merge` 被 git-lfs 的 `other-*` 链接接管，不走 lefthook，所以恢复挂在 pre-commit 上。
- 手动恢复：`npm run internal:restore`
- **AI agent：开工前发现 `specs/` 或 `.workbuddy/` 缺失、或其中某个目录是空的，先跑 `npm run internal:restore` 再继续**，不要报"文档丢失"。
- **merge / 切分支前，本分支新写或改过的内容先跑 `npm run internal:archive`**——归档仓只在这次同步时才会拿到新内容，否则切走就没了。

### 同步与获取

```bash
npm run internal:status         # 看本地与归档仓的漂移
npm run internal:archive        # 本地 → 私有归档（只同步当前工作区）
npm run internal:restore        # 私有归档 → 本地
npm run internal:archive:all    # 扫所有 worktree，把漂移全收进归档仓
```

`internal:archive` 只管当前工作区；写在一个 worktree 里、没归档就切走的内容会永久丢失（已经发生过一次）。`internal:archive:all` 按内容哈希 + mtime 扫全部 worktree 补齐，是防丢的真正兜底，**已配每日自动跑**。

脚本：`scripts/internal-sync.sh`。两个目录的差异：`specs/` pull 时跳过仍在版本控制里的白名单子目录（避免冲掉未提交改动）；`.workbuddy/` pull 时带 `-u`，本地更新的文件不覆盖（那是 IDE 刚写的实时状态）。

归档仓位置不写在仓库里，从环境变量 `INTERNAL_ARCHIVE_DIR` 或 `~/.config/cloudbase-mcp/internal-archive-dir` 读取；没配置时脚本静默跳过，不阻塞 git 操作。

**新机器**：

```bash
git clone git@github.com:binggg/cloudbase-mcp-specs-archive.git ~/Projects/cloudbase-mcp-specs-archive
mkdir -p ~/.config/cloudbase-mcp
printf '%s\n' "$HOME/Projects/cloudbase-mcp-specs-archive" > ~/.config/cloudbase-mcp/internal-archive-dir
```

- 私有归档仓：`binggg/cloudbase-mcp-specs-archive`（PRIVATE，main 分支），顶层同时放 `specs/` 与 `.workbuddy/`
- 公开仓库的 git **历史**里仍能看到旧 spec 与 `.workbuddy/` 文件（只做了最新版本移除，未 rewrite）
- 对外产物（`config/source/skills/`、`plugin/`、`doc/`、IDE command 模板）里提到的 `specs/` 指的是**使用者自己项目**里的目录，与本仓库的归档约定无关，不要往那里写私有归档信息
</internal_dirs>

<attribution_evaluation_guardrails>
当任务来源于 failing eval、attribution issue、grader、benchmark、trace、result artifact 或其他评测证据时，必须额外遵守以下规则：
1. 评测证据只用于定位问题，不等于产品公开契约；先判断是否存在真实用户可见的产品缺陷，再决定是否修改产品代码。
2. 不要为了通过评测而新增 benchmark-only / grader-only 的兼容分支、提示词、注释、文案或行为。
3. 不要新增同一语义字段的多套命名变体（例如大小写/下划线别名）来"兼容评测"，除非该别名已经是文档化的公开契约。
4. 不要在代码、注释、文档、提交说明或 PR 描述中泄漏内部评测文件名或上下文路径（例如 `run-result.json`、`run-trace.json`、`evaluation-trace.json`、`.codebuddy/attribution-context`）；如必须提及，统一改写为"internal evaluation evidence"。
5. 如果证据更像 grader / task contract 问题、仓库路由错误、或外部系统限制，而不是当前仓库里的真实产品缺陷，应停止产品表面改动，并在总结里明确说明原因与后续建议。
6. 提交前必须自查 staged diff：确认没有评测专用措辞、没有内部 artifact 泄漏、没有为同一字段临时补多个别名。
</attribution_evaluation_guardrails>

<cloud_api_backend_rules>
1. 如果需求涉及通过调用腾讯云 API 来实现后端功能，开始设计或编码前必须先查阅相关文档：
   - 云 API 文档：https://cloud.tencent.com/document/product/876/34809
   - 依赖 API 文档：https://cloud.tencent.com/document/product/876/34808
2. 同时必须检查 CloudBase Manager SDK 文档：https://docs.cloudbase.net/api-reference/manager/node/introduction
3. 如果 Manager SDK 有对应方法，优先使用 Manager SDK；只有在 SDK 没有对应能力或无法满足需求时，才直接调用腾讯云 API。
4. 在实现前，需要根据文档确认接口能力、参数、鉴权方式、返回结构和限制条件，避免凭记忆实现。
</cloud_api_backend_rules>