中文 · English
Dev Mesh 是面向多个 Agent 共享同一个 Git 工作区的当前代协同层。它为短周期工作提供明确 权限，处理工作重叠，串行化协作式 Git 发布，并留下可在事后检查的有界证据。
系统有意保持本地化和轻量：普通的非重叠修改只经过一个 Run 和一个可复用 Claim；只有实际贡献 源码字节时才产生 Work Result，无修改检查直接释放。Git 提交是可选且独立的发布步骤；只有不同 Run 实际发生重叠时，才会进入争用处理、临时分支和微事务。
当前启用的权限合同是 [email protected]。这是第二代实现，但协议使用不可变
的 YYYYMMDD.x 标识，而不是持续变化的 v2 标签。可选且兼容的跨项目证据合同是
[email protected]。
Observer 可只读采集 20260814.1 与 20260823.1 来源，并把来源版本显式记录在本地目录库；
这不会放宽 Producer 的写入合同，未知版本只显示为适配提示，不伪装成采集故障。
工作区权限位于 .dev-mesh/。从 20260814.1 切换时，旧权限状态和更早的完整 archive 都会
被丢弃，只在 .dev-mesh/coord/analysis/ 保留去内容化、有界且无权限含义的事件证据。
已退役的 .agent-coordination/ 仍只保留用于阻止旧写入方的 tombstone。退役流程见
docs/CUTOVER.md。
- Run — 一个 Agent 任务在一个 Git 工作区中的执行身份。
- Claim — 该 Run 可以修改的精确路径和语义资源。
- Work Result — 完成工作的非权限证据；它释放 Claim，但不声称已提交或提供私有回滚点。
- Workspace bytes — 对明确声明的 Git ignored 小文件记录有界内容指纹，使其也能完成 Work Result 和 baseline 接力；它不创建分支、不提交数据，也不替代数据库事务。
- Contention — Claim 重叠时，待写入方可以直接等待；只有重分配、交接、独占或分支卸载 会进入双方确认。
- 受管 Git 发布 — 直接提交和事务发布共享一个 canonical Git fence，避免协作 Agent 争用 工作区 index 或分支。
- Events — 低频、不可变的生命周期证据；heartbeat 只更新快照，不产生事件流量。
- Observer 和 Console — 只读投影、诊断、协作流和跨项目证据；它们不授予或重建权限。
Dev Mesh 记录通信，但不负责投递。Agent 必须先通过宿主环境的任务控制能力联系、创建或恢复
真实目标任务，再用 Dev Mesh 记录已经成功执行的动作。send、ack 和 handoff 命令本身不会
启动或唤醒另一个任务。
Dev Mesh 通过 Glenzli Marketplace 发布。首次使用时先登记 marketplace，再安装 Dev Mesh：
codex plugin marketplace add glenzli/marketplace --ref main
codex plugin add dev-mesh@glenzli-marketplace第一条命令只需执行一次；以后可从同一 marketplace 显式安装或更新插件。安装后，
coordinate-shared-workspace 与 observe-dev-mesh 会作为同一版本的技能一起提供；不要长期把全局
技能直接软链到此源码仓库。安装或更新后，请在新任务中使用新版本。
发布版本采用纯 MAJOR.MINOR.PATCH，不追加构建后缀；版本只表达功能兼容性。安装包对应的
完整源码提交单独记录在 release metadata 的 source_revision 中，不混入插件版本。
维护者从干净的源码提交构建最小安装包，再显式同步到 plugin collection 的工作树；同步不会提交或 推送任何仓库：
python3 scripts/plugin_dist.py build
python3 scripts/plugin_dist.py sync \
--package dist/dev-mesh --marketplace-root ../marketplace --replace构建器只复制运行所需的 manifest、assets、skills、runtime、当前 schemas 与 current contracts；
tests、archive、协调状态及缓存不会进入 dist。
coordinate-shared-workspace 提供协作操作说明。
普通路径是：
检查 -> 加入 Run -> 创建或复用 Claim -> 编辑 -> 验证
-> 按实际贡献完成或直接释放 -> 离开 Run
\
-> 可选受管发布
同一 Run 已有 Claim 覆盖请求时会直接复用，不生成自争用；没有跨 Run 重叠时，不会引入额外
协调流程。claim-finish 只为实际源码贡献建立 Work Result。返回的 next_action 发现不同 Run
重叠或恢复需求时，技能才会把 Agent 路由到对应的争用、事务或恢复步骤。
最常见的重叠不需要完整协商：后到的 Claim 自动进入待仲裁状态，选择等待后，原 Claim 完成
即可激活。parallel-tx 不是两个 Agent 同时离开主线，而是把待写入方卸载到一个短命分支；
只有双方都声明了互不相交的语义写资源时才能选择它。继承 dirty baseline 时，接受动作同时绑定
内容摘要、canonical revision 和分支；其间任一项变化都会返回新证据，要求 Agent 再确认一次。
下面的 Console 示例由真实的项目关系和协作流组件使用虚拟数据渲染，用于说明视觉语义， 不是生产活动截图。
项目视图区分显式绑定且由接收方确认的跨任务协作，与较弱的同 Run 线索。实线箭头表示已记录 的协作关系；虚线括号只表示同一个 Owner/Run 身份出现在多个工作区中，它是线索，不是任务间 发生通信的证明。
协作流只投影不同 Run 之间的争用、交接、依赖、事务和恢复。普通 Run/Claim 生命周期不会为了 填充图表而展开；需要追溯时再从折叠的原始事件区查看。
同一 plugin 中独立的 observe-dev-mesh 技能把当前控制面采集到外部
SQLite catalog，并启动仅监听 loopback 的 Web Console：
python3 skills/observe-dev-mesh/scripts/console.py \
--db /absolute/path/observer.sqlite3 \
--root /absolute/project-parent \
--host 127.0.0.1 --port 8765Console 默认展示当前权限风险、不同 Run 之间的争用、交接、依赖、恢复和跨项目关系；普通 生命周期被折叠，原始事件仅在按需审计区展开。Catalog 位于被观测工作区之外；Observer 对源 工作区保持只读。
在 macOS 上，移动仓库或更换 Python runtime 后，可安装仓库自带的 LaunchAgent，使 Console 持续运行：
python3 scripts/install_console_service.py install
python3 scripts/install_console_service.py status服务默认还会通过 [email protected] 发布经过脱敏的
[email protected] Unix socket offer。Registration 是发现证据，不代表
服务仍然存活；消费者仍需连接当前 endpoint 进行确认。
runtime/dev_mesh_coord/— 权限、Work Result、dirty baseline、争用、 可恢复 Git effect、受管提交、微事务和跨项目关系生产端。runtime/dev_mesh_observer/— 有界源验证、catalog、诊断和报告。runtime/dev_mesh_console/— loopback API、采集生命周期和浏览器 看板。runtime/tests/— 协议、崩溃窗口、并发、Observer、Console 和切换测试。skills/— 面向 Agent 的薄启动器和操作说明；协议逻辑仍由 runtime 持有。contracts/和schemas/— 规范性的公共协议表面。DESIGN.md— 架构边界、状态布局和深入导航。
协议或跨边界修改使用完整验证门：
PYTHONPATH=runtime python3 -m unittest discover -s runtime/tests -v
PYTHONPATH=runtime python3 -m compileall -q \
runtime/dev_mesh_coord runtime/dev_mesh_observer runtime/dev_mesh_console runtime/tests
python3 skills/coordinate-shared-workspace/scripts/coord.py --help
python3 skills/observe-dev-mesh/scripts/console.py --help对于有界的文档或展示修改，先运行能够证明链接、命令或渲染组件正确的聚焦检查，再按风险决定 是否升级到完整验证门。