git:20260911.c0a8750 to git:20260911.7d77b1d

# devloop plugin — 设计与开发指南

面向二次开发者。使用向（装 / 配 / 跑）见 [`README.md`](./README.md)；共享术语见 [`CONCEPTS.md`](./CONCEPTS.md)。

---

## 项目定位与边界

**devloop 的领域职责是管理 PR/MR 的创建、开发与验证生命周期**：

```

enter repo → 基于 branch 开发 → 按 Component 验证 → commit / push → 创建 PR/MR → 人工 merge

```

**领域主链是 `PR/MR → Repo → Component`**：PR/MR 始终锚定一个 repo；repo 是 git、branch、forge 状态和提交历史的边界；component 是 repo 内 build/lint/test 的验证单位。Branch 是开发生命周期主轴；面向多 session 并发时，worktree 是 branch 的一种特殊形态。

**Workspace 是运行上下文，不是 PR/MR 的归属边界**：它可以聚合多个 repo，为项目知识和多 session 协作提供共同根；单仓库模式同样完整支持。跨 repo Requirement 与长期编排由 Baton/reqloop 拥有，devloop 不维护需求状态机。

**目录按 owner 表达这个模型**：TypeScript `domain/` 承载 Workspace / Repo / Component、Board、branch/PR 状态与合法变化；`lib/` 提供 Git、forge、ecosystem、config、parser 等技术能力；`adapters/` 与 `hooks/` 只翻译各 Harness 的事件和输出。skill 调用的 Git/release/validation/review workflow 保留在 `scripts/` 的 Python 子树中，其辅助 `domain/lib/tasks` 也是 script-private，不得被 Harness runtime 依赖或复制 TypeScript Board/policy 语义。

AGENTS.md 是项目边界与 References 的**文字知识源**；`.devloop/*.json` 是由 hooks、scripts、monitors 从 git、forge、验证命令和文字源派生的**结构化运行态**。Board 在两者之上组织当前 session 相关的紧凑视图并投递给 prompt。三者共同服务于同一个目标：让 LLM 对 workspace/repo 的作用可控、可观测、可验证。一轮循环的端到端时序见 [`docs/loop.md`](./docs/loop.md)。

**两个控制杠杆**：

1. **Board 消除信息滞后**：状态源持续提供当前 subproject 的 branch / 工作区 / PR / validation，加上 workspace 级的子项目清单与 AGENTS.md References；Board 按相关性组织 payload-first 条目，以独立的 item kind、delivery channel、prompt scope 与 replay policy 决定投递——AI 改第一行前就掌握现状，长历史又不浪费 prompt token。

2. **执行守卫提前拒绝高置信风险**：PreToolUse `deny` 覆盖保护分支、过期分支改文件和误带文件等常见路径；command hook 超时、异常或 Harness 未覆盖的执行路径会 fail-open，因此它是护栏而非安全边界。

**边界**：

- 聚合 workspace 与单 repo 都是运行形态，workspace 可选；子项目从文件系统发现，手工 init 不是前置。

- 只管 PR/MR 生命周期内的 repo/branch、开发入口和验证控制；**不做**问题发现与 trace、部署、通用 git 教学。

---

## 代码地图与核心模块

```

devloop/

├── .claude-plugin/plugin.json # Claude manifest（靠目录约定自动发现）

├── index.ts # npm 公共 API

├── adapters/ # Harness 薄适配层

│ ├── claude.ts codex.ts # stdin/stdout hook dialect

│ ├── process-hooks.ts # Claude/Codex lifecycle translation

│ └── dsh.ts # 原生 Cordis plugin（ctx.on）

├── domain/ # TypeScript 领域 owner

│ ├── repo.ts # ★Repo/Component WorkSet 与内容指纹

│ ├── workspace.ts # ★Workspace 注册、发现与归属

│ ├── repo-layout.ts # ★Component 模型 + repo/component 路径边界

│ ├── context/ # ★状态源：workspace/session/gate/store

│ ├── board/ # ★Board model/projection/view/delivery/render/runtime

│ └── forge.ts # ★PullRequest/Comment/Release 中立模型 + Forge port

├── lib/ # TypeScript 技术能力：被 domain/adapters 消费

│ ├── process.ts git-state.ts # ★统一 command seam 与 git/branch/worktree 事实

│ ├── forge/ # ★GitHub/GitLab 平级 adapter + HTTP/按 repo 分发

│ ├── ecosystem/ # ★工具链身份、环境准备与 canonical fallback

│ └── config.ts parsers.ts # ★配置持久化与文字源解析

├── hooks/ # 共享 policy engine + 进程 hook 入口

│ ├── hooks.json # Claude 事件注册

│ ├── hooks.codex.json # Codex 事件注册（含 SessionEnd + PostToolUse 刷新）

│ ├── runtime.ts # Claude/Codex stdin/stdout executable

│ ├── core/ # Change→Target→Rule→Decision + 三端统一投影

│ ├── rules/index.ts # 保护分支、owner、validation、layer 等规则

│ └── friction.ts # guard deny → friction ledger adapter

├── tasks/tasks.json # 共享 task 发现描述

├── scripts/ # skill-owned Python workflow，不进入 Harness runtime

│ ├── *.py # git / validation / review / task CLI 入口

│ ├── domain/ lib/ tasks/ # workflow-private 辅助包

│ └── tests/ # Python workflow 回归测试

├── monitors/monitors.json # Claude native-monitor adapter：循环调用共享 task

├── commands/ # slash：enter / gcam / gcamp / gcampr（validation 归 skill，gate 自动触发）

└── config/ # config.example.json 模板；全局配置在 ~/.devloop/config.json，repo/workspace 可在 .devloop/config.json 就近覆盖

```

---

## 关键约定

1. **领域归属沿 `PR/MR → Repo → Component`**：PR/MR 与 branch 生命周期归 Repo，验证范围与验证结果归 Component；Workspace 只聚合上下文。不得重新引入“一个 repo 只有一个代码目录”的假设，具体选择与身份语义见 [`CONCEPTS.md`](./CONCEPTS.md)。

2. **Harness runtime 只走 TypeScript**：`adapters/hooks → domain/lib`；`domain/` 持有共享事实和合法变化，`lib/` 提供 Git、forge、配置等技术能力。`scripts/` 的 Python workflow 是 skill-owned 的独立执行面，不得成为 Harness adapter 的依赖。

3. **状态源提供事实，Board 决定组织和投递，guard 读取 live truth**：AGENTS.md 是文字知识源，`.devloop/` 是结构化运行态；Repo、Branch、WorkingTree 与 Session 状态按归属和写入者隔离，验证戳按 Component 记录。Board 只维护 per-session 投递游标，不复制业务事实，也不参与硬门禁判定。详见 [`docs/board.md`](./docs/board.md) 与 [`CONCEPTS.md`](./CONCEPTS.md)。

4. **生命周期动作走唯一入口，合法例外才软提示**：新工作在编辑前走 `branch.py create`，branch 创建规则归 `domain.branch`；commit/push/PR 走 `commit_flow`/smart 脚本并复用同一 branch 事务；checkout 选择及 worktree 形态的创建、复用和清理走 `checkout.py` / `domain.worktree`，PR/MR 状态到 checkout 动作的映射归 `pull_request_lifecycle`。保护分支、失活分支、guest session 等无合法编辑路径的情况硬拦截，有合法例外的 in-flight PR/MR 只注入提示。具体流程见 [`docs/loop.md`](./docs/loop.md) 与 [`docs/lifecycle-hooks.md`](./docs/lifecycle-hooks.md)。

5. **devloop 产出开发事实，不拥有长期业务 loop 或会话唤醒**：task 可维护结构化状态，并对 devloop 自有本地资源执行有界、幂等的 desired-state reconciliation；Harness monitor / scheduler 只重复触发它。跨系统持久观察、调度和后续工作仍归 Baton/reqloop；不要在 Plugin 内重建通知 transport、waiter 或 re-arm 流程。

---

## References

- 一轮循环端到端流程（事件 → hook/script → 状态）：[`docs/loop.md`](./docs/loop.md)

- Board 上下文读模型（事实源 → Board/View → channel/scope/replay policy）：[`docs/board.md`](./docs/board.md)

- devops 生命周期 hook（pre_commit/post_commit/pre_mr/post_mr，统一 lint/test/review 等的触发；hook 皆阻塞，异步结果写结构化状态供下一轮或外部控制面观察）：[`docs/lifecycle-hooks.md`](./docs/lifecycle-hooks.md)

- Worktree 依赖环境（checkout-local 依赖视图 + 共享包缓存；生态 prepare 与验证前置条件）：[`docs/worktree-env.md`](./docs/worktree-env.md)

- 提交期 code-review（signal hook `review`，任意相位由 config 决定：detach 起、审全量 diff、不挡 commit、结果经 Board pull 投递；分支有开放 MR 时（典型 post_mr）机会性发评论到 MR 做历史）：[`docs/code-review.md`](./docs/code-review.md)

- 使用 / 安装 / 配置：[`README.md`](./README.md)

- 共享术语（repo_dir / **component** + default component / 保护分支 / PR 模型 / 验证状态 / `<PLUGIN_ROOT>`）：[`CONCEPTS.md`](./CONCEPTS.md)

- 仓库级（marketplace / 多 CLI）：[`../AGENTS.md`](../AGENTS.md)

- 完整方案与设计决策：plan 文档（开发者本地 `~/.claude/plans/devloop-plugin-0.1.md`）

- Harness adapter 边界与事件映射：[`docs/harness-adapters.md`](./docs/harness-adapters.md)