AGENTS.md · diff
git:20260911.ded210f to git:20260911.7d77b1d
5 added, 4 removed. Audit A to A.
# devloop
devloop 是跨 CLI 的 plugin marketplace，根目录下每个 plugin 独立交付和演进。`devloop/devloop`
是首个 Plugin，承载开发闭环；`code-taste` 提供设计判断 skill，`quality` 提供基于执行证据的质量
评估 skill，`example` 是占位示例。
---
## 项目定位与边界
devloop 托管聚焦开发者效率的 plugin 集合。本仓库**根层**只负责：
- 多 plugin marketplace 的索引（`.claude-plugin/marketplace.json` 等）
- 跨 plugin / 跨 CLI 的共用约定（`<PLUGIN_ROOT>` 占位、CLI-agnostic 共享路径布局）
- 多 CLI 接入位置约定（Claude / Codex / DeepSeek Harness / opencode）
明确**不在本文档展开**的内容：
- 具体 plugin 的设计动机、内部架构、hook 列表、状态文件、配置项 → 见对应 `<plugin>/README.md`
- 整个工作流落地的方案记录（feature 矩阵、版本规划等）→ 见 plan 文档
- 当前实施范围：`devloop` 支持 Claude Code、Codex 与 DeepSeek Harness。Claude/Codex 通过薄进程 hook adapter 接入，DSH 通过原生 Cordis plugin 接入；三端共用 TypeScript Board、state、tool projection 与 policy。skill 调用的 Git/release/validation/review 脚本继续使用 Python。opencode 侧目前只有 `example` 占位 plugin 演示 marketplace 结构。
+ 当前实施范围：`devloop` 支持 Claude Code、Codex 与 DeepSeek Harness。Claude/Codex 通过薄进程 hook adapter 接入；DSH bundle 同时挂载原生 Cordis adapter 并暴露包内 skills。三端共用 TypeScript Board、state、tool projection 与 policy。skill 调用的 Git/release/validation/review 脚本继续使用 Python。opencode 侧目前只有 `example` 占位 plugin 演示 marketplace 结构。
---
## 代码地图与核心模块
```
devloop/ # ← 仓库根（marketplace）
│
├── .claude-plugin/marketplace.json # Claude marketplace 索引
├── .agents/plugins/marketplace.json # Codex marketplace 索引（Codex 标准路径）
├── .opencode/marketplace.json # opencode marketplace 索引（占位，按协议补）
│
├── devloop/ # plugin: 开发者日常工作流（Claude + Codex + DSH）
│ │ # git / MR / lint / test / cwd-aware context / Board / 执行守卫
│ │ # Claude 用 CwdChanged / FileChanged / native monitor；Codex 用 SessionEnd + Scheduled tasks
│ ├── .claude-plugin/plugin.json # Claude manifest
│ ├── .codex-plugin/plugin.json # Codex manifest（hooks 指向 hooks.codex.json）
+ │ ├── cordis.patch.yml # DSH bundle layer（挂载 adapter + 暴露 skills）
│ ├── skills/ # 7 个 skill（CLI 共享，含一次性 monitor reconciliation）
│ ├── commands/ # slash commands（Claude 端）
│ ├── adapters/ # Claude/Codex hook dialect + DSH Cordis adapter
│ ├── domain/ # TS 共享领域模型与状态
│ ├── lib/ # TS 共享技术 seam
│ ├── hooks/ # TS policy/runtime 与 hook manifests
│ ├── tasks/ # 周期 task 的发现描述
│ ├── scripts/ # skill-owned Python workflow 及其私有 domain/lib/tasks
│ ├── config/ # 用户配置模板（config.json：workspaces / gitlab / precommit）
│ ├── monitors/monitors.json # Claude MR-sweep 后台轮询
│ └── README.md / AGENTS.md / CONCEPTS.md
│
├── code-taste/ # plugin: 架构、边界、命名与可维护性判断（skill-only）
│ ├── .claude-plugin/plugin.json # Claude manifest
│ ├── .codex-plugin/plugin.json # Codex manifest
│ ├── skills/code-taste/ # 共享 skill 与分层 references
│ └── README.md
│
├── quality/ # plugin: 基于项目真实测试资产的质量评估（skill-only）
│ ├── .claude-plugin/plugin.json # Claude manifest
│ ├── .codex-plugin/plugin.json # Codex manifest
│ ├── references/environment.md # E2E / Perf 共用的 Target、Runner、连接与准备契约
│ ├── skills/e2e/ # 操作项目已有 E2E 能力，并渐进补充项目自有覆盖
│ ├── skills/perf/ # 操作项目已有压力/容量能力，并解释或比较运行证据
│ ├── skills/trajectory/ # 评估 Agent 轨迹并组织效果/成本调优
│ └── README.md
│
├── example/ # plugin: 占位演示，证明这是多 plugin marketplace
│ ├── .claude-plugin/plugin.json # Claude ✅
│ ├── .codex-plugin/plugin.json # Codex ✅
│ └── commands/hello.md
│
├── scripts/ # 仓库级工具脚本（跨 plugin），如版本号 bump
│ └── bump_plugin_version.py # 被 `make bump-version` 调用
├── Makefile # 仓库级入口（`make help` 查看）
├── AGENTS.md # 本文档（仓库级）
├── README.md # 用户向 marketplace 总览（安装方式）
└── CONTRIBUTING.md # 新 plugin 接入规范
```
- **CLI 范围差异**：`devloop` 当前支持 Claude Code、Codex 与 DSH。`skills/` 共享；`commands/` 仍是 Claude slash command 入口，Codex 无同构 slash command，主要由 skill 名 + bundled hooks 作为入口；DSH 直接加载 `@compforge/devloop/dsh`。Claude 的 native monitor 与 Codex Scheduled task 分别驱动同一个一次性 reconciliation 入口。opencode 待协议明确。
+ **CLI 范围差异**：`devloop` 当前支持 Claude Code、Codex 与 DSH。`skills/` 共享；`commands/` 仍是 Claude slash command 入口，Codex 无同构 slash command，主要由 skill 名 + bundled hooks 作为入口；DSH bundle 暴露同一组 skills，并加载 `@compforge/devloop/dsh`。Claude 的 native monitor 与 Codex Scheduled task 分别驱动同一个一次性 reconciliation 入口。opencode 待协议明确。
详细：[`devloop/README.md`](./devloop/README.md)（使用向） · [`devloop/AGENTS.md`](./devloop/AGENTS.md)（开发向）。
---
## 关键约定
### `<PLUGIN_ROOT>` 占位符（跨 plugin 通用）
按"谁来解析"分两层处理，两层都不需要为新 CLI 做 sed：
**(1) 配置文件层（CLI 解析）**——`hooks/hooks.json` / `plugin.json` 这种由 CLI 直接读取的配置文件：
- 命令字符串里**统一写 `${CLAUDE_PLUGIN_ROOT}`**。
- Claude Code 原生认这个占位符；Codex 提供 `PLUGIN_ROOT` 作为标准名，同时保留 `CLAUDE_PLUGIN_ROOT` / `CLAUDE_PLUGIN_DATA` 作为兼容别名。
- Codex 还额外提供 `PLUGIN_DATA`（可写数据目录）供插件持久化状态。
- - **单一 `hooks/hooks.json` 跨 Claude / Codex 复用**，业务代码零修改。
+ - Claude 使用 `hooks/hooks.json`，Codex 使用 `hooks/hooks.codex.json`；两个 manifest 显式选择 Harness 身份，并进入同一套 TypeScript runtime/core。
**(2) 文档/SKILL.md 层（AI 解析）**——人写给 AI 看的 markdown：
- 写 `<PLUGIN_ROOT>` 占位，AI 执行时按当前 CLI 映射到实际 env 变量值。
- Claude → `${CLAUDE_PLUGIN_ROOT}`；Codex → `${PLUGIN_ROOT}`（`CLAUDE_PLUGIN_ROOT` 亦可用，为兼容别名）。
加新 CLI 时：配置文件层多半零改动（如果新 CLI 也兼容 `CLAUDE_PLUGIN_ROOT`），文档层在 AI 提示词里多列一行映射即可。
### CLI-agnostic 共享路径布局
每个 plugin 内部建议以下目录跨 CLI 共享：
- - `<plugin>/skills/`、`<plugin>/commands/`、`<plugin>/scripts/`：内容 CLI 无关
+ - `<plugin>/skills/`、`<plugin>/commands/`：内容 CLI 无关
- `<plugin>/domain/`：TypeScript 领域模型、状态变化与生命周期规则；归属看领域事实的 owner
- `<plugin>/lib/`：TypeScript 跨入口技术能力和外部适配，不放领域对象
- `<plugin>/hooks/`：TypeScript 事件 adapter，依赖 `domain/lib`
- `<plugin>/scripts/`：skill-owned workflow；允许保留 Python 及其私有辅助包，但 Harness runtime 不得依赖它
Codex 与 Claude 的 command hook 都使用 stdin/stdout JSON，但支持事件和 payload 细节不能靠猜测合并；manifest 显式设置 Harness 身份，adapter 再映射到共享 TypeScript core。opencode 待协议明确时再决定差异隔离层。
### 加新 plugin 的流程
1. 新建 `<plugin>/` 子目录
2. 写需要支持的 CLI 的 manifest（`.claude-plugin/plugin.json` 等）
3. 在每个 CLI 的 `marketplace.json` 追加一项
4. 写 `<plugin>/README.md`，至少包含：能做什么、安装、配置、限制
5. 遵守 `<PLUGIN_ROOT>` 与共享路径布局约定
### 改动 plugin 后：bump 版本号
影响用户体验的 plugin 改动，跑 `make bump-version PLUGIN=<name>`（详见 `make help`）——否则 `/plugin update` 拉不到新版。
---
## References
- 各 plugin 使用 / 安装 / 配置：`<plugin>/README.md`
- 各 plugin 设计与开发：`<plugin>/AGENTS.md`
- 各 plugin 内跨 skill 共享术语：`<plugin>/CONCEPTS.md`（若有）