dsh-punky-swarm 0.3.6

package/README.en.md

@@ -0,0 +1,281 @@
+# dsh-punky-swarm — Punky Swarm (Cluster Governance)
+
+![license](https://img.shields.io/badge/license-AGPL--3.0-blue) ![node](https://img.shields.io/badge/node-%3E%3D22-green) ![CI](https://github.com/Punky971210/dsh-punky-swarm/actions/workflows/ci.yml/badge.svg)
+
+> A dsh (DeepSeek Harness) **single-machine multi-subagent cluster governance** plugin: wavePlan three-layer DAG (fixed semantics, never recomputed after batch creation) + engine-level gates (Entry / Plan contract / Exit / Complete) + state machine + lock/mailbox + session isolation + task difficulty routing gate + national-standard AIP compatibility + governance capability enhancements (heartbeat/watchdog, worktree physical isolation, acceptance evidence, mailbox loop protection, diagnostics bridging, log export). Ships with the Punky Swarm preset and jiufeng-team role guide.
+
+中文: [README.md](README.md)
+
+## Scope
+
+- **Goal**: dsh **single-machine multi-subagent governance** — govern a cohort of workers inside the same dsh process (batches / gates / communication / recovery re-dispatch);
+- **Out of scope**: distributed cluster sync, cost control, model tiering; resume only provides checkpoint preservation and recovery audit (failed lanes stay terminal, redo opens a new batch).
+
+## Design Purpose and Origins
+
+**Purpose**: gates (Entry/Plan contract/Exit/Complete) together with batches, locks, mailbox and other mechanisms exist to **keep the pipeline and the cluster stable**, not to restrict agent freedom — the tool layer is fully open to agents, the pattern layer only guides, and team assembly is pluggable; tasks are graded by size (Leader assignment → single-agent fallback).
+
+**Origins**: this project grew out of the trade-off between single-agent full pipelines and graph-style orchestration:
+
+- Single-agent full pipeline (design → execution → testing): heavy human involvement, the human becomes the pipeline bottleneck;
+- Graph-style orchestration (LangGraph direction): tried and abandoned — flow hard-coded into graphs, costly to change, agent freedom crushed;
+- Compromise: implemented on an early Swarm cluster runtime following the "jiufeng" working pattern (Leader decomposition → multi-role collaboration → gate adjudication), then migrated into dsh to become this plugin.
+
+## The Three Components
+
+| Component | Location | Contents |
+|---|---|---|
+| Plugin | packages/dsh-punky-swarm | Engine: **20 governance tools** + Tier3 gates + session isolation v2 + read-only API (incl. AIP /tools endpoint) + task difficulty gate + Punky swarm cluster monitoring panel |
+| Pattern | packages/dsh-punky-swarm/presets/jiufeng | Punky Swarm preset: Leader persona + governance discipline + tool-bootstrap |
+| Guide | packages/dsh-punky-swarm/skills/jiufeng-team | 3-layer 8-role × operation-manual assembly table + constitution + templates |
+
+## Installation
+
+> The instructions below target Agent / automated execution; commands can be run directly; `web` is an example profile and can be replaced.
+> The plugin **auto-syncs** the pattern preset (→ `~/.dsh/.agent-presets/jiufeng`) and skill guide (→ `~/.agents/skills/jiufeng-team`) on startup — **no manual placement needed**; if present and identical it is skipped, otherwise it is overwritten with the packaged version.
+
+```sh
+git clone https://github.com/Punky971210/dsh-punky-swarm.git
+cd dsh-punky-swarm
+# Install peer dependencies (@deepseek-ai/dsh-tools, @deepseek-ai/cordis; versions pinned by package-lock.json)
+npm ci --prefix packages/dsh-punky-swarm
+# POSIX
+dsh plugin --profile web add link:$(pwd)/packages/dsh-punky-swarm
+# Windows PowerShell
+dsh plugin --profile web add link:$PWD\packages\dsh-punky-swarm
+dsh web restart
+```
+
+> It can also be installed via npm: `npm install -g dsh-punky-swarm` (version see [package.json](packages/dsh-punky-swarm/package.json)); git source + dsh plugin link is the development/debugging route.
+
+### npm installation
+
+```sh
+npm install -g dsh-punky-swarm
+dsh plugin --profile web add dsh-punky-swarm
+dsh web restart
+```
+
+> The `dsh plugin add` usage for the npm package is subject to post-release verification (from 0.3.1).
+
+## Punky Swarm Cluster Monitoring Panel (read-only)
+
+The plugin ships with a **Punky swarm cluster** monitoring panel: third tab "对话 / 轨迹 / 蟛蜞集群" in the session header (conversation.view), **available on install, no extra configuration**.
+
+- **Batch list**: phase (planning/running/complete…) + terminal progress `3/5` + auto-release/completed marks;
+- **Stats bar**: total batches / running / completed / abnormal (failed+conflict);
+- **Batch detail**: lane status cards (status + task summary + gate missing-item details + layer/dependencies), event timeline, inbox (dispatch/broadcast) counts;
+- **Read-only**: 3s auto-refresh, follows Web UI light/dark theme; the execution engine (batch/gate/state machine) **cannot be modified by humans, view only**; governance operations are executed by the Punky Swarm Leader.
+
+## Governance Tools (20)
+
+> Scope premise (P1-01 unified): **20 is the full-open (cordis.patch.yml) count** — `log_export` is included only when `logs.enabled: true`.
+> Under the bare default config (no `capabilities` key), 7 keys are on by default (aip/discovery/verify/watch/worktree/budget/trajectory),
+> giving 19 tools (without `log_export`); `logs` defaults off and is turned on by the patch to reach 20. Explicit `enabled: false` disables per-key.
+
+Grouped by function:
+
+### Batch planning
+| Tool | Description |
+|---|---|
+| `wave_plan` | Create batches layered into waves by dependency DAG (fixed semantics, never recomputed after creation) |
+| `batch_phase` | Batch phase transitions (planning→running→paused→aborted/complete) |
+| `batch_status` | Query batch status (phase/lanes/wavePlan/event summary) |
+
+### Task grading and gates
+| Tool | Description |
+|---|---|
+| `assign_check` | Task difficulty judgment A/B/C and execution entity (guard gate basis) |
+| `gate_status` | Query lane gate status (consume/produce/outputs missing-item lists) |
+| `artifact_types` | Query artifact type registry (layer/directory prefix conventions) |
+
+### Assets and locks
+| Tool | Description |
+|---|---|
+| `asset_claim` | Claim Leader-produced artifacts as batch assets (copied into the engine artifact root) |
+| `lane_claim` | Claim a lane with an O_EXCL single-writer lock (conflict rejected first) |
+| `lane_release` | Release a lane lock |
+
+### Member status
+| Tool | Description |
+|---|---|
+| `member_status` | Member status operations (pending/running/review/idle) |
+| `member_settle` | Member settlement (merged/failed/skipped/conflict, with gate validation) |
+
+### Communication (mailbox)
+| Tool | Description |
+|---|---|
+| `mailbox_send` | Send messages (inbox/outbox/broadcast, atomic write + ackId) |
+| `mailbox_read` | Read unacknowledged messages |
+| `mailbox_ack` | Acknowledge consumed messages |
+
+### Heartbeat and expiry detection
+| Tool | Description |
+|---|---|
+| `lane_heartbeat` | Lane heartbeat query/trigger (watchdog scan, stalled marking) |
+
+### worktree physical isolation
+| Tool | Description |
+|---|---|
+| `lane_worktree_create` | Create an independent git worktree for a lane (baselined from orch HEAD) |
+| `lane_worktree_merge` | Merge a lane branch into orch (conflict preserves scene + manifest) |
+| `lane_checkpoint` | In-lane checkpoint commit (git add+commit, preserves artifacts) |
+| `lane_checkpoint_status` | Query checkpoint history and progress (resume-contract entry point) |
+
+### Logs
+| Tool | Description |
+|---|---|
+| `log_export` | Read-only event-stream export (lane/type/since filters + json/markdown + landing in engine artifact root) |
+
+> Assembly switches (cordis.patch.yml): aip / discovery / verify / watch / worktree / budget / trajectory / logs default enabled, each can be explicitly disabled with `enabled: false`; mergeAgent default disabled (requires host-injected spawner). Default-off capabilities: `aip.identity` (identity system) and `acps` (ACPs communication, see next chapter).
+
+## National Standard AIP Compatibility
+
+Compatible with the Agent-Interconnection national standard (GB/Z 185-2026) tool/agent descriptor structures — additive only, no changes to existing behavior, pluggable:
+
+- **Tool 6 attributes**: every tool provides toolId / name / description / version / inputParam / outputParam (toolId = `dsh.punky-swarm.<name>` reverse-domain unique; inputParam/outputParam are JSON Schemas, required always present);
+- **Agent descriptor (GB/Z 185.4-2026 Part 4: Agent Description; ACS field set)**: assembly config → per-role ACS AgentCapabilitySpec descriptor (root object 20 keys = 14 required: aic / active / lastModifiedTime / protocolVersion / name / description / version / provider / securitySchemes / endPoints / capabilities / defaultInputModes / defaultOutputModes / skills, 6 optional: iconUrl / documentationUrl / webAppUrl / entityUserId / entityMeta / certificate; AgentSkill 8 keys = 5 required: id / name / description / version / tags, 3 optional: examples / inputModes / outputModes; protocol 02.01);
+- **Message/task/session mapping**: mailbox messages, wavePlan tasks, batch status → national-standard structures (pure mapping, read-only, storage unchanged, ackId atomic write preserved);
+- **Identity system** (default off, activated by `aip.identity.enabled=true`): AIC identity code (OID prefix `1.2.156.3088` + CRC-16/CCITT-FALSE + Base36 check digit) + CAI identity certificate + pluggable signing (default ECDSA-P256 / RSA-2048) + trust-chain verification; SM2 not supported (signing interface is pluggable, defaults ECDSA-P256 / RSA-2048, `algorithm='sm2'` explicitly rejected);
+- **Assembly switch**: `aip.enabled` (default on) → generates tool 6-attribute catalog + `GET /api/dsh-punky-swarm/tools` (filterable with `?name=`).
+
+## ACPs Communication (off by default)
+
+ACPs (Agent Communication Protocol Standard) communication capability: external mTLS service endpoint + internal mailbox↔ACPs bridge + registry semi-automatic registration and external ADP discovery integration. **All off by default** (secure default) — both `acps.enabled` and `acps.endpoint.enabled` default to `false`; listeners/clients load only when explicitly enabled; when off there is zero runtime footprint (no listeners, no timers, no network).
+
+### Capability overview
+
+| Capability | Assembly key | Default | Purpose |
+|---|---|---|---|
+| External mTLS endpoint | `acps.enabled` + `acps.endpoint.enabled` | Off | External AIP JSON-RPC / ACS / health check (TLSv1.3 + mutual certificates) |
+| Internal bridge | `acps.bridge` | Off (inbound additionally sub-gated off) | In-process bidirectional mailbox ↔ ACPs message projection/delivery |
+| registry registration | `acps.registry` | Off | Semi-automatic registration client (requires registry.url + user credentials) |
+| discovery discovery | `acps.discovery` | Off | External ADP discovery client (POST /discover) |
+
+### External mTLS service endpoint
+
+Standalone HTTPS listener (native node:https + node:tls, zero new dependencies), default port `9443` (`acps.endpoint.port` configurable), host default `127.0.0.1`; TLSv1.3 (`minVersion` default, TLSv1.2 configurable) + mutual certificates (`requestCert` + `rejectUnauthorized` = CERT_REQUIRED); `devInsecure` is an explicit development-only switch (default `false`, production downgrade not allowed). Assembly condition: `acps.enabled` AND `acps.endpoint.enabled` **both true**; missing/unusable certificates → startup warning and stay disabled, does not block the main process.
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/acps/rpc` | POST | AIP JSON-RPC (jsonrpc 2.0, method=`rpc`, params.command=TaskCommand → TaskResult accepted/rejected); client certificate CN must be a valid AIC (otherwise 400) |
+| `/.well-known/acs.json` | GET | Direct ACS fetch (14 required keys + securitySchemes.mutualTLS + endPoints JSONRPC) |
+| `/health` | GET | Health check (agent/status/tasks/groups) |
+
+Certificates: CA self-signed (native node:crypto X.509 + ECDSA P-256), entity certificate CN=AIC, SAN=URI:acps://{AIC}, generated by default under `<root>/acps/certs` (ca.pem/ca.key/server.pem/server.key); `cert/key/ca` three paths configurable to override.
+
+### Internal bridge
+
+`acps.bridge` (in-process bidirectional, default off; mode=`inprocess`):
+- **inbound** (default off, enable explicitly with `acps.bridge.inbound=true`): external ACPs TaskCommand → mailbox message, **written atomically to inbox via the lib/comms/mailbox.js public interface (ackId generated by mailbox, never bypassed, no side-channel writes)**; write target is inbox only (lane derived from mentions/groupId into meta), outbox is not externally writable, external broadcast delivery unsupported;
+- **outbound**: mailbox messages → ACPs Message/TaskResult (reuses the aip-format three mappings), projection/delivery view only, never writes back to mailbox storage;
+- **/rpc→bridge wiring**: TaskCommand received at `POST /acps/rpc` lands in mailbox via `handleInbound`; when `bridge.inbound=false`, protocol-level `rejected` (INBOUND_DISABLED, HTTP 200 returned — transport succeeded, protocol layer rejected); when bridge is not assembled, falls back to standalone endpoint `accepted` (backward compatible);
+- **mailbox red lines preserved**: ackId atomic write, three boxes (inbox/outbox/broadcast), lane isolation semantics preserved verbatim;
+- **zero path**: when `enabled=false`, nothing loads or instantiates (mountBridge returns null).
+
+### registry / discovery integration (off by default)
+
+- **registry** (`acps.registry`, semi-automatic registration client): requires `registry.url` + user credentials (username/password or token, injected via config/env, never hard-coded, never committed); flow login → upsertAgent → submitAgent (**human approval, never auto-skipped**) → requestEab → queryAcs; EAB macKey stored encrypted with **AES-256-GCM** (when `eabKey` is unconfigured, plaintext credentials are returned for the caller to store itself);
+- **discovery** (`acps.discovery`, ADP client): POST `{baseUrl}/discover` to query external agents (4 type categories / 34 operators, sharing protocol constants with local discovery); `scope` = local (existing local catalog only) / external (external only) / both (local+external merged, external takes precedence in acsMap); timeout default 10s, limit default 5.
+
+### Configuration example
+
+```yaml
+# ACPs communication capability (all off by default, secure default)
+acps:
+  enabled: true                # capability master switch
+  endpoint:
+    enabled: true              # external mTLS endpoint (both this and the master switch must be true to assemble)
+    port: 9443                 # default 9443
+    host: 127.0.0.1            # localhost only by default
+    certDir: null              # default <root>/acps/certs (auto-generated)
+    minVersion: TLSv1.3        # default TLSv1.3 (TLSv1.2 allowed)
+    devInsecure: false         # explicit development only; no production downgrade
+  bridge:
+    enabled: false             # internal bridge (in-process bidirectional)
+    inbound: false             # external writes to mailbox require explicit true
+  registry:
+    enabled: false             # semi-automatic registration
+    url: null                  # registry public API base URL (required)
+    username: null             # injected via config/env, never hard-coded
+    password: null
+    eabKey: null               # EAB macKey encryption key (AES-256-GCM)
+  discovery:
+    enabled: false             # external ADP discovery client
+    baseUrl: ''                # external discovery-server root address
+    scope: local               # local / external / both
+    timeout: 10000             # default 10s
+    limit: 5                   # default result cap
+```
+
+### Relationship with existing AIP capabilities
+
+- Existing endpoints (`GET /api/dsh-punky-swarm/tools`, `GET /api/dsh-punky-swarm/agents`, `POST /api/dsh-punky-swarm/discover`, `GET /.well-known/aip`) **remain byte-for-byte unchanged** — ACPs uses an independent 9443 listener + `/acps/*` prefix, zero path conflicts;
+- Existing local discovery (`capabilities.discovery`, default on) is the in-process query channel; `acps.discovery` is the external query channel; `scope=both` merges both channels' results;
+- Existing assets reused by ACPs communication: `aip-format` three mappings (Message/TaskCommand/Session), `lib/aip/identity.js` (AIC validation/certificates), `lib/discovery/schema.js` (protocol constants and validation);
+- Same as `aip.identity` (default off), this is a default-off capability; CAPABILITY_REGISTRY now has 9 keys (aip/identity/discovery/verify/watch/worktree/budget/trajectory/acps).
+
+### Capability boundaries (not implemented)
+
+- **Tool calling (GB/Z 185.7-2026 Part 7: Agent Tool Calling)**: not implemented;
+- **SM2 signing**: not supported — sign is a pluggable interface, defaults ECDSA-P256 / RSA-2048, `algorithm='sm2'` explicitly rejected;
+- **mini-ADSP**: external `/discover` server semantics only reserve the function signature (createMiniAdsp), not implemented;
+
+## Governance Capabilities
+
+| Capability | Assembly key | Mechanism |
+|---|---|---|
+| Heartbeat/expiry detection | `capabilities.watch` | watchdog timer + lane_heartbeat tool; backoff-tier follow-ups + N consecutive no-activity beats → lane.stalled mark |
+| worktree physical isolation | `capabilities.worktree` | lane_worktree_create/merge/checkpoint (git worktree isolation + checkpoint commits); complements the lane_claim logical lock |
+| Acceptance evidence | `capabilities.verify` | post-execute evidence capture (content-addressed blob + ledger) + three-state adjudication (done/failed/blocked) + completion gate (advisory/enforce) |
+| Mailbox loop protection | `capabilities.budget` | chain-hop cap / per-ordered-pair round-trip cap / duplicate-message rejection; inbox exempt |
+| Diagnostics bridging | `capabilities.trajectory` | anomaly diagnosis (deadlock/invalid retry/goal drift) → sessionId→lane mapping → notify (autoFail default off) |
+| Log export | `capabilities.logs` | log_export tool: read-only event-stream projection, lane/type/since filters + json/markdown + engine artifact root landing (escape-proof) |
+| topic subscription | — (pure module) | subscribeTopic/emitTopic: in-process dispatch + mailbox broadcast landing (ackId atomic write) |
+| merge agent | `worktree.mergeAgent` (default off) | conflict-semantics resolution (requires a host-injected spawner; without injection the conflict stays unresolved) |
+
+## Lifecycle
+
+- **lane conditions**: statically declared at batch creation (dependency artifacts/files exist), validated before dispatch, unsatisfied → skipped;
+- **archive auto-archiving**: after complete, one-way auto-archive (artifacts packaged and kept queryable, not rollback-able);
+- **needHuman hold**: audit artifact declares needHuman → lane held at review, Manager relays the human verdict (merged/conflict), no new member state;
+- **ratchet rule table**: state-transition config (delete-only, never add; allowRelax escape hatch default off);
+- **recovery mechanism**: checkpoint preservation + recovery audit + crash→idle re-dispatch (new workers can query checkpoints to skip completed steps); resume interface reserved.
+
+## wavePlan (fixed semantics)
+
+- On batch creation, tasks are layered into waves by dependency DAG; **never recomputed mid-flight after creation** (fixed wavePlan semantics);
+- Tasks may declare layer (plan/exec/audit), consume/produce/outputs, role/skills; team assembly injects skill prefixes by role (pluggable, not bound to jiufeng);
+- Same-wave tasks dispatch in parallel; batch/member status uses the state file as the single source of truth (event log auditable).
+
+## Task Difficulty Gate
+
+- **Before any action on each (user) turn**, the Leader must give a task difficulty A/B/C and execution entity via assign_check: A=Leader direct / B=single subagent / C=cluster wave_plan batch;
+- **default to C**: the evaluation object is the complete target task (scope=full); any C feature (multi-step ≥3 / multi-role ≥2 / gate needed / external dependency / recoverability) → C; when unsure, fill C;
+- **guard enforced**: after a C judgment, calling execution tools (pwsh/write/edit/run/subagent, etc.) without creating a batch is rejected by the engine; unassessed/expired assessments (20 execution calls or 30 minutes) are likewise rejected; read-only queries unrestricted;
+- **asset_claim**: exploration/troubleshooting artifacts the Leader produced directly before a C judgment can be claimed as batch assets via asset_claim, no rework.
+
+## Tier3 Gates
+
+- **Batch-creation static validation**: layer ∈ plan/exec/audit; exec implies audit; artifact path contracts; cross-layer references; tamper resistance;
+- **Entry**: consume artifacts complete before exec dispatch, missing → dispatch rejected (GATE_ENTRY_MISSING);
+- **Plan contract (artifact structure gate)**: plan artifacts must contain required spec sections (acceptance criteria/constraints) + valid-JSON task tree, missing → merged rejected (GATE_PLAN_CONTRACT);
+- **Exit (artifact gate)**: outputs landed before exec settlement, produce landed before audit settlement, missing → merged rejected (GATE_EXIT_MISSING_*);
+- **Complete (closing gate)**: before batch complete, audit-layer acceptance done with no failed/conflict and exec layer fully terminal (GATE_COMPLETE_*);
+- **Hardening (dp1-dp4) = the above gates engine-ized** (mapping see skills/jiufeng-team/references/workflow.md §四): dp1 assignment judgment → Entry + assign_check; dp2 completion confirmation → Exit; dp3 review routing → review + member_settle; dp4 acceptance judgment → Complete — implemented capability, moved out of "out of scope".
+
+generic batches (no layer) do not trigger gates, backward compatible.
+
+## State Machine
+
+```
+Member: pending -> running -> review -> merged | failed | skipped | conflict (idle=recovery re-dispatch; review->running=rework)
+Batch: planning -> running -> paused -> aborted | complete (complete requires the three-layer gates first)
+```
+
+## License and Commercial Licensing
+
+This project is licensed under **GNU AGPL v3 (AGPL-3.0) as its sole license**:
+
+- Under [AGPL-3.0](LICENSE), free to use, modify, and distribute (including commercially); if you provide the modified software over a network as a service, you must publish your modifications under AGPL-3.0.
+- For other licensing (e.g., closed-source commercial use), please contact the author.

package/README.md

@@ -0,0 +1,281 @@
+# dsh-punky-swarm — 蟛蜞模式（Punky Swarm 集群治理）
+
+![license](https://img.shields.io/badge/license-AGPL--3.0-blue) ![node](https://img.shields.io/badge/node-%3E%3D22-green) ![CI](https://github.com/Punky971210/dsh-punky-swarm/actions/workflows/ci.yml/badge.svg)
+
+> dsh（DeepSeek Harness）**单机多子 agent 集群治理**插件：wavePlan 三层 DAG（固定语义，建批后不重算）+ 引擎级门禁（Entry / Plan 契约 / Exit / Complete）+ 状态机 + 锁/mailbox + 会话隔离 + 任务难度路由门禁 + 国标 AIP 兼容 + 治理能力增强（心跳/watchdog、worktree 物理隔离、验收证据、mailbox 环防护、诊断桥接、日志导出）。附蟛蜞模式预设与 jiufeng-team 角色指引。
+
+English: [README.en.md](README.en.md)
+
+## 边界（Scope）
+
+- **目标**：dsh **单机多子 agent 治理**——在同一 dsh 进程内治理一批 worker（批次 / 门禁 / 通信 / 恢复重置派发）；
+- **范围外**：分布式集群同步、成本控制、模型分层路由；续跑仅提供 checkpoint 保全与恢复审计（失败 lane 仍终态、重做仍开新批次）。
+
+## 设计目的与由来
+
+**目的**：门禁（Entry/Plan 契约/Exit/Complete）与批次、锁、mailbox 等机制的核心目的，是**保障流水线与集群的稳定运行**，而非限制 Agent 自由度——工具层对 Agent 全量开放，模式层只给指引，团队装配可插拔；任务按规模分级（Leader 指派 → 单 Agent 降级）。
+
+**由来**：本项目源于单 Agent 全流程与图式编排之间的取舍：
+
+- 单 Agent 全流程（设计→执行→测试）：人工介入重，人成为流程瓶颈；
+- 图式编排（LangGraph 方向）：尝试后放弃——流程写死成图，改动成本高，Agent 自由度被压死；
+- 折中：按「九峰」工作模式（Leader 拆解 → 多角色协作 → 门禁裁决）在早期 Swarm 集群运行时上落地，随后迁移到 dsh 成为本插件。
+
+## 三件套
+
+| 件 | 位置 | 内容 |
+|---|---|---|
+| 插件 | packages/dsh-punky-swarm | 引擎：**20 治理工具** + Tier3 门禁 + 会话隔离 v2 + 只读 API（含 AIP /tools 端点）+ 任务难度门禁 + 蟛蜞集群监控面板 |
+| 模式 | packages/dsh-punky-swarm/presets/jiufeng | 蟛蜞模式预设：Leader persona + 治理纪律 + tool-bootstrap |
+| 指引 | packages/dsh-punky-swarm/skills/jiufeng-team | 3 层 8 角色 × 操作手册装配表 + constitution + 模板 |
+
+## 安装
+
+> 以下指引面向 Agent / 自动化执行，命令可直接运行；`web` 为示例 profile，可替换。
+> 插件启动时**自动同步**模式预设（→ `~/.dsh/.agent-presets/jiufeng`）与技能指引（→ `~/.agents/skills/jiufeng-team`），**无需手动放置**；已存在且内容一致则跳过，不一致则覆盖为包内版本。
+
+```sh
+git clone https://github.com/Punky971210/dsh-punky-swarm.git
+cd dsh-punky-swarm
+# 安装 peer 依赖（@deepseek-ai/dsh-tools、@deepseek-ai/cordis，版本由 package-lock.json 固定）
+npm ci --prefix packages/dsh-punky-swarm
+# POSIX
+dsh plugin --profile web add link:$(pwd)/packages/dsh-punky-swarm
+# Windows PowerShell
+dsh plugin --profile web add link:$PWD\packages\dsh-punky-swarm
+dsh web restart
+```
+
+> 也可通过 npm 安装：`npm install -g dsh-punky-swarm`（版本见 [package.json](packages/dsh-punky-swarm/package.json)）；git 源码 + dsh plugin link 为开发/调试方式。
+
+### npm 安装
+
+```sh
+npm install -g dsh-punky-swarm
+dsh plugin --profile web add dsh-punky-swarm
+dsh web restart
+```
+
+> npm 包的 `dsh plugin add` 用法以发布后实际验证为准（0.3.1 起）。
+
+## 蟛蜞集群监控面板（只读）
+
+插件自带 **蟛蜞集群** 监控面板：会话区头部「对话 / 轨迹 / 蟛蜞集群」第三分页（conversation.view），**安装即得，无需额外配置**。
+
+- **批次列表**：阶段（planning/running/complete…）+ 终态进度 `3/5` + 可自动放行/已完结标记；
+- **统计条**：总批次 / 运行中 / 已完结 / 异常（failed+conflict）；
+- **批次详情**：lane 状态卡（状态 + 任务简述 + 门禁缺件明细 + 层/依赖）、事件时间线、收件箱（派发/广播）计数；
+- **只读**：3s 自动刷新，跟随 Web UI 深浅主题；执行引擎（批次/门禁/状态机）**人工不可修改，只能查看**，治理操作由蟛蜞模式 Leader 执行。
+
+## 治理工具（20）
+
+> 口径前提（P1-01 统一）：**20 为 cordis.patch.yml 全开口径**（`logs.enabled: true` 时含 `log_export`）。
+> 缺省配置（config 无 capabilities 键）下 7 键默认开（aip/discovery/verify/watch/worktree/budget/trajectory），
+> 工具总数 19（不含 `log_export`）；`logs` 默认关，patch 显式开启后达 20。显式 `enabled: false` 可逐键关闭。
+
+按功能分类：
+
+### 批次规划
+| 工具 | 说明 |
+|---|---|
+| `wave_plan` | 按依赖 DAG 分层为 waves 建批（固定语义，建批后不重算） |
+| `batch_phase` | 批次阶段迁移（planning→running→paused→aborted/complete） |
+| `batch_status` | 查询批次状态（phase/lanes/wavePlan/事件摘要） |
+
+### 任务分级与门禁
+| 工具 | 说明 |
+|---|---|
+| `assign_check` | 任务难度判定 A/B/C 与执行主体（guard 门禁依据） |
+| `gate_status` | 查询 lane 门禁状态（consume/produce/outputs 缺件清单） |
+| `artifact_types` | 查询产物类型注册表（层/目录前缀约定） |
+
+### 资产与锁
+| 工具 | 说明 |
+|---|---|
+| `asset_claim` | 已直做产物归位为批次资产（复制入引擎产物根） |
+| `lane_claim` | 以 O_EXCL 单写者锁认领 lane（冲突先拒） |
+| `lane_release` | 释放 lane 锁 |
+
+### 成员状态
+| 工具 | 说明 |
+|---|---|
+| `member_status` | 成员状态操作（pending/running/review/idle） |
+| `member_settle` | 成员结算（merged/failed/skipped/conflict，含门禁校验） |
+
+### 通信（mailbox）
+| 工具 | 说明 |
+|---|---|
+| `mailbox_send` | 发送消息（inbox/outbox/broadcast，原子写 + ackId） |
+| `mailbox_read` | 读取未确认消息 |
+| `mailbox_ack` | 确认消费消息 |
+
+### 心跳与过期检测
+| 工具 | 说明 |
+|---|---|
+| `lane_heartbeat` | lane 心跳查询/触发（watchdog 扫描，stalled 标记） |
+
+### worktree 物理隔离
+| 工具 | 说明 |
+|---|---|
+| `lane_worktree_create` | 为 lane 建独立 git worktree（从 orch HEAD 基线） |
+| `lane_worktree_merge` | 合并 lane 分支进 orch（冲突保留现场 + 清单） |
+| `lane_checkpoint` | lane 内 checkpoint 提交（git add+commit，保产物） |
+| `lane_checkpoint_status` | 查询 checkpoint 历史与进度（续跑契约入口） |
+
+### 日志
+| 工具 | 说明 |
+|---|---|
+| `log_export` | 只读事件流导出（lane/type/since 过滤 + json/markdown + 引擎产物根落盘） |
+
+> 装配开关（cordis.patch.yml）：aip / discovery / verify / watch / worktree / budget / trajectory / logs 默认开启，可显式 `enabled: false` 逐键关闭；mergeAgent 默认关闭（需宿主注入 spawner）。默认关能力：`aip.identity`（身份体系）与 `acps`（ACPs 通讯，见下章）。
+
+## 国标 AIP 兼容
+
+兼容《人工智能 智能体互联》国标（GB/Z 185-2026）工具/智能体描述结构，仅增不改、可插拔：
+
+- **工具 6 属性**：每工具提供 toolId / name / description / version / inputParam / outputParam（toolId = `dsh.punky-swarm.<name>` 反向域唯一；inputParam/outputParam 为 JSON Schema，required 恒在）；
+- **智能体描述（GB/Z 185.4-2026 第 4 部分：智能体描述；ACS 字段集）**：装配配置 → 每角色 ACS AgentCapabilitySpec 描述（根对象 20 键 = 必填 14：aic / active / lastModifiedTime / protocolVersion / name / description / version / provider / securitySchemes / endPoints / capabilities / defaultInputModes / defaultOutputModes / skills，可选 6：iconUrl / documentationUrl / webAppUrl / entityUserId / entityMeta / certificate；AgentSkill 8 键 = 必填 5：id / name / description / version / tags，可选 3：examples / inputModes / outputModes；协议 02.01）；
+- **消息/任务/会话映射**：mailbox 消息、wavePlan 任务、批次状态 → 国标结构（纯映射只读不改存储，ackId 原子写保留）；
+- **身份体系**（默认关，`aip.identity.enabled=true` 激活）：AIC 身份码（OID 前缀 `1.2.156.3088` + CRC-16/CCITT-FALSE + Base36 校验码）+ CAI 身份证书 + 可插拔签名（默认 ECDSA-P256 / RSA-2048）+ 信任链验证；SM2 暂不支持（签名接口可插拔，默认 ECDSA-P256 / RSA-2048，`algorithm='sm2'` 显式拒绝）；
+- **装配开关**：`aip.enabled`（默认开启）→ 生成工具 6 属性目录 + `GET /api/dsh-punky-swarm/tools`（可 `?name=` 过滤）。
+
+## ACPs 通讯方式（默认关）
+
+ACPs（Agent Communication Protocol Standard）通讯能力：对外 mTLS 服务端点 + 内部 mailbox↔ACPs 桥接 + registry 半自动注册与外部 ADP 发现对接。**全部默认关**（安全默认）——`acps.enabled` 与 `acps.endpoint.enabled` 均默认 `false`，显式开启才加载监听/客户端，关闭时零运行时路径（无监听、无定时器、无网络）。
+
+### 能力总览
+
+| 能力 | 装配键 | 默认 | 用途 |
+|---|---|---|---|
+| 对外 mTLS 端点 | `acps.enabled` + `acps.endpoint.enabled` | 关 | 对外提供 AIP JSON-RPC / ACS / 健康检查（TLSv1.3 + 双向证书） |
+| 内部桥接 | `acps.bridge` | 关（inbound 再子门控关） | mailbox ↔ ACPs 消息进程内双向投影/投递 |
+| registry 注册 | `acps.registry` | 关 | 半自动注册客户端（需 registry.url + 用户凭据） |
+| discovery 发现 | `acps.discovery` | 关 | 外部 ADP 发现客户端（POST /discover） |
+
+### 对外 mTLS 服务端点
+
+独立 HTTPS 监听器（node:https + node:tls 原生，零新依赖），默认端口 `9443`（`acps.endpoint.port` 可配）、host 默认 `127.0.0.1`；TLSv1.3（`minVersion` 默认，可配 TLSv1.2）+ 双向证书（`requestCert` + `rejectUnauthorized` = CERT_REQUIRED）；`devInsecure` 仅显式开发开关（默认 `false`，生产不允许降级）。装配条件：`acps.enabled` 与 `acps.endpoint.enabled` **双真**；证书缺失/不可用 → 启动告警并保持禁用，不阻塞主进程。
+
+| 端点 | 方法 | 说明 |
+|---|---|---|
+| `/acps/rpc` | POST | AIP JSON-RPC（jsonrpc 2.0，method=`rpc`，params.command=TaskCommand → TaskResult accepted/rejected）；客户端证书 CN 须为合法 AIC（否则 400） |
+| `/.well-known/acs.json` | GET | ACS 直取（14 必填键 + securitySchemes.mutualTLS + endPoints JSONRPC） |
+| `/health` | GET | 健康检查（agent/status/tasks/groups） |
+
+证书：CA 自签（node:crypto 原生 X.509 + ECDSA P-256），实体证书 CN=AIC、SAN=URI:acps://{AIC}，默认生成于 `<root>/acps/certs`（ca.pem/ca.key/server.pem/server.key）；`cert/key/ca` 三路径可配置覆盖。
+
+### 内部桥接
+
+`acps.bridge`（进程内双向，默认关；mode=`inprocess`）：
+- **inbound**（默认关，`acps.bridge.inbound=true` 显式开启）：外部 ACPs TaskCommand → mailbox 消息，**经 lib/comms/mailbox.js 公共接口原子写 inbox（ackId 由 mailbox 生成，绝不绕过、无旁路写）**；写入目标仅 inbox（按 mentions/groupId 推导 lane 进 meta），outbox 不可外部直接写，broadcast 外部投递不支持；
+- **outbound**：mailbox 消息 → ACPs Message/TaskResult（复用 aip-format 三映射），只投影/投递视图，不反写 mailbox 存储；
+- **/rpc→bridge 接线**：`POST /acps/rpc` 收到的 TaskCommand 经 `handleInbound` 落 mailbox；`bridge.inbound=false` 时协议级 `rejected`（INBOUND_DISABLED，HTTP 200 返回——传输成功、协议层拒绝）；bridge 未装配时回端点缺省 accepted（向后兼容）；
+- **mailbox 红线保留**：ackId 原子写、三 box（inbox/outbox/broadcast）、lane 隔离语义逐字保留；
+- **零路径**：`enabled=false` 时不加载不实例化（mountBridge 返回 null）。
+
+### registry / discovery 对接（默认关）
+
+- **registry**（`acps.registry`，半自动注册客户端）：需 `registry.url` + 用户凭据（username/password 或 token，config/env 注入，不硬编码不落仓库）；流程 login → upsertAgent → submitAgent（**人工审批，不自动化跳过**）→ requestEab → queryAcs；EAB macKey **AES-256-GCM 加密存证**（`eabKey` 未配置时仅返回明文凭据由调用方自存）；
+- **discovery**（`acps.discovery`，ADP 客户端）：POST `{baseUrl}/discover` 查询外部 Agent（type 四类 / 34 运算符，与本地 discovery 共享协议常量）；`scope` = local（仅本地既有目录）/ external（仅外部）/ both（本地+外部合并，acsMap 外部优先）；timeout 默认 10s、limit 默认 5。
+
+### 配置示例
+
+```yaml
+# ACPs 通讯能力（全部默认关，安全默认）
+acps:
+  enabled: true                # 能力总开关
+  endpoint:
+    enabled: true              # 对外 mTLS 端点（与总开关双真才装配）
+    port: 9443                 # 默认 9443
+    host: 127.0.0.1            # 默认仅本机
+    certDir: null              # 缺省 <root>/acps/certs（自动生成）
+    minVersion: TLSv1.3        # 默认 TLSv1.3（可 TLSv1.2）
+    devInsecure: false         # 仅显式开发；生产不允许降级
+  bridge:
+    enabled: false             # 内部桥（进程内双向）
+    inbound: false             # 外部写 mailbox 需显式 true
+  registry:
+    enabled: false             # 半自动注册
+    url: null                  # registry public API 基址（必需）
+    username: null             # config/env 注入，不硬编码
+    password: null
+    eabKey: null               # EAB macKey 加密存证密钥（AES-256-GCM）
+  discovery:
+    enabled: false             # 外部 ADP 发现客户端
+    baseUrl: ''                # 外部 discovery-server 根地址
+    scope: local               # local / external / both
+    timeout: 10000             # 默认 10s
+    limit: 5                   # 默认返回上限
+```
+
+### 与既有 AIP 能力的关系
+
+- 既有端点（`GET /api/dsh-punky-swarm/tools`、`GET /api/dsh-punky-swarm/agents`、`POST /api/dsh-punky-swarm/discover`、`GET /.well-known/aip`）**一字不动**——ACPs 对外独立 9443 监听 + `/acps/*` 前缀，路径零冲突；
+- 既有本地发现（`capabilities.discovery`，默认开）为进程内查询通道；`acps.discovery` 为外部查询通道，`scope=both` 时合并两通道结果；
+- ACPs 通讯复用的既有资产：`aip-format` 三映射（Message/TaskCommand/Session）、`lib/aip/identity.js`（AIC 校验/证书）、`lib/discovery/schema.js`（协议常量与校验）；
+- 与 `aip.identity`（默认关）同属默认关能力；CAPABILITY_REGISTRY 现 9 键（aip/identity/discovery/verify/watch/worktree/budget/trajectory/acps）。
+
+### 能力边界（未实现）
+
+- **工具调用（GB/Z 185.7-2026 第 7 部分：智能体工具调用）**：未实现；
+- **SM2 签名**：暂不支持——sign 为可插拔接口，默认 ECDSA-P256 / RSA-2048，`algorithm='sm2'` 显式拒绝；
+- **mini-ADSP**：对外 `/discover` 服务端语义仅预留函数签名（createMiniAdsp），未实现；
+
+## 治理能力
+
+| 能力 | 装配键 | 机制 |
+|---|---|---|
+| 心跳/过期检测 | `capabilities.watch` | watchdog 定时器 + lane_heartbeat 工具；退避档位追问 + 连续 N 拍无活动 → lane.stalled 标记 |
+| worktree 物理隔离 | `capabilities.worktree` | lane_worktree_create/merge/checkpoint（git worktree 隔离 + checkpoint 提交）；与 lane_claim 逻辑锁互补 |
+| 验收证据 | `capabilities.verify` | post-execute 证据捕获（内容寻址 blob + ledger）+ 三态裁决（done/failed/blocked）+ 完成门禁（advisory/enforce） |
+| mailbox 环防护 | `capabilities.budget` | 链跳数上限 / 同有序对往返上限 / 重复消息拒发；inbox 豁免 |
+| 诊断桥接 | `capabilities.trajectory` | 异常诊断（死锁/无效重试/目标漂移）→ sessionId→lane 映射 → notify（autoFail 默认关） |
+| 日志导出 | `capabilities.logs` | log_export 工具：只读事件流投影，lane/type/since 过滤 + json/markdown + 引擎产物根落盘（防逃逸） |
+| topic 订阅 | —（纯模块） | subscribeTopic/emitTopic：进程内分发 + mailbox broadcast 落盘（ackId 原子写） |
+| merge agent | `worktree.mergeAgent`（默认关） | 冲突语义化解（需宿主注入 spawner；未注入 spawner 时保持 conflict 状态） |
+
+## 生命周期
+
+- **lane 条件**：建批静态声明（依赖产物/文件存在），派发前校验，不满足落 skipped；
+- **archive 自动归档**：complete 后自动单向归档（产物打包保留可查，不可回滚）；
+- **needHuman 人工挂起**：audit 产物声明 needHuman → lane 挂 review，Manager 转达人工裁决（merged/conflict），不新增成员态；
+- **棘轮规则表**：状态迁移配置化（只许删不许增，allowRelax 逃生门默认关）；
+- **恢复机制**：checkpoint 保全 + 恢复审计 + 崩溃后 idle 归位重派（新 worker 可查 checkpoint 跳过已完成步骤）；断点续跑接口预留。
+
+## wavePlan（固定语义）
+
+- 建批时按任务依赖 DAG 分层为 waves，**批次创建后绝不中途重算**（wavePlan 固定语义）；
+- 任务可声明 layer（plan/exec/audit）、consume/produce/outputs、role/skills；team 装配按 role 注入 skill 前缀（可插拔，不绑定 jiufeng）；
+- 同 wave 可并行派发；批次/成员状态以状态文件为唯一事实源（事件日志可审计）。
+
+## 任务难度门禁（Task Difficulty Gate）
+
+- **每轮（user turn）动手执行前**，Leader 须经 assign_check 给出任务难度 A/B/C 与执行主体：A=Leader 直做 / B=单个 subagent / C=集群 wave_plan 建批；
+- **default to C**：评估对象是完整目标任务（scope=full），任一 C 特征（多环节≥3 / 多角色≥2 / 需门禁 / 外部依赖 / 可恢复性）即判 C；拿不准就填 C；
+- **guard 强制**：判 C 后未建批即调用执行型工具（pwsh/write/edit/run/subagent 等）会被引擎拒绝；未评估/评估过期（20 次执行调用或 30 分钟）同样拒绝，只读查询不受限；
+- **asset_claim**：判 C 前 Leader 已直做的探索/排障产物，可用 asset_claim 归位为批次资产，不返工。
+
+## 三层门禁（Tier3）
+
+- **建批静态校验**：layer ∈ plan/exec/audit；有 exec 必有 audit；产物路径契约；跨层引用；防篡改；
+- **Entry（入口门禁）**：exec 派发前 consume 产物齐备，缺则拒派（GATE_ENTRY_MISSING）；
+- **Plan 契约（产物结构门禁）**：plan 产物须含 spec 必填章节（验收标准/约束）+ task-tree 合法 JSON，缺失则拒 merged（GATE_PLAN_CONTRACT）；
+- **Exit（产出门禁）**：exec 结算前 outputs 落盘、audit 结算前 produce 落盘，缺则拒 merged（GATE_EXIT_MISSING_*）；
+- **Complete（收尾门禁）**：批次 complete 前 audit 层验收完成且无 failed/conflict、exec 层全终态（GATE_COMPLETE_*）；
+- **硬化（dp1-dp4）= 上述门禁引擎化**（映射见 skills/jiufeng-team/references/workflow.md §四）：dp1 分配判定 → Entry + assign_check；dp2 完成确认 → Exit；dp3 审查路由 → review + member_settle；dp4 验收判定 → Complete——属已实现能力，从「范围外」移除。
+
+generic 批次（无 layer）不触发门禁，向后兼容。
+
+## 状态机
+
+```
+成员：pending -> running -> review -> merged | failed | skipped | conflict（idle=恢复重派；review->running=返工）
+批次：planning -> running -> paused -> aborted | complete（complete 前置三层门禁）
+```
+
+## 许可与商业授权
+
+本项目以 **GNU AGPL v3（AGPL-3.0）为唯一许可**：
+
+- 在遵守 [AGPL-3.0](LICENSE) 的前提下，可自由使用、修改、分发（含商用）；若修改后通过网络提供服务，须按 AGPL-3.0 公开修改内容。
+- 如需其他许可（如闭源商用），请联系作者获得许可。

package/cordis.patch.yml

@@ -0,0 +1,59 @@
+# dsh-punky-swarm bundle patch — the layer applied when a profile lists this bundle.
+- insert:
+    - id: dsh-punky-swarm
+      name: 'dsh-punky-swarm'
+      config:
+        # AIP 装配开关：enabled=true 时生成 14 工具 6 属性目录并挂载 GET /api/dsh-punky-swarm/tools；
+        # 默认 true（AIP 兼容为主线；目录生成 + 只读 /tools 端点，零新增工具、零行为破坏）。
+        # toolVersion 可选覆盖引擎版本。关闭（false）则零运行时开销，行为与既有版本完全一致。
+        aip:
+          enabled: true
+        # 能力补全装配（默认全开——AIP 为主线 + 治理能力全开；显式 enabled:false 可逐键关闭）
+        # 诊断桥接（trajectory）：订阅 trajectory 异常 → sessionId→lane 映射 → notify（默认 notify-only，不自动结算）；
+        #   autoFail=false（默认）异常不自动 member_settle failed；failConfidence 为 loop_deadlock 自动 failed 的置信阈值。
+        capabilities:
+          # 发现服务（ADP）：enabled=true 时挂载 POST /api/dsh-punky-swarm/discover +
+          #   GET /.well-known/aip（消费 tool catalog + agent-descriptor 目录）；nodes 可逐节点 active=false 隐藏（默认 active=true）。
+          discovery:
+            enabled: true
+          trajectory:
+            enabled: true
+            autoFail: false
+            failConfidence: 0.85
+          # mailbox 环防护（budget）：enabled=true 时 outbox/broadcast 发送前经 checkBudget——
+          #   maxChainHops（链跳数上限）/maxChainRoundTrips（有序对往返上限）可配；inbox（Leader→worker 下行派发）永不受限；
+          #   显式 enabled:false 可关闭（关闭时现有 mailbox 调用零感知：不声明 meta.chain = 恒新链，不被拒）。
+          budget:
+            enabled: true
+            maxChainHops: 4
+            maxChainRoundTrips: 2
+          # lane 过期检测（watch/heartbeat）：enabled=true 时挂 watchdog 定时器并注册 lane_heartbeat 工具——
+          #   intervalsMinutes 退避档位（分钟，默认 [10,20,30]，冷场越久追问间隔越长）；maxMissed 硬停拍数
+          #   （默认 3，连续 N 拍无活动 → appendEvent('lane.stalled') 停止追问，只标记不自动处置）；
+          #   scanIntervalMinutes watchdog 扫描间隔（默认 1）；probeTemplate 可选覆写追问模板（{lane}/{batchId}/{missed} 占位）。
+          watch:
+            enabled: true
+          # worktree 物理隔离（lane-tools）：enabled=true 时注册 lane_worktree_create / lane_worktree_merge / lane_checkpoint
+          # （git worktree 隔离 + checkpoint 提交；与 lane_claim 逻辑锁互补——lane_claim 管状态层「写谁的」，
+          #  本组工具管工作区层「写到哪」；全能力默认开 → 工具总数 18（14+heartbeat+worktree 三件+log_export），回归已覆盖）。
+          worktree:
+            enabled: true
+            # merge agent 装配键：enabled=true 且宿主注入 mergeAgentSpawner 时，
+            #   lane_worktree_merge 冲突可派 LLM merge agent 语义化解（taskswarm merger 借鉴）；model 可选模型名；
+            #   timeoutMs 超时毫秒（默认 600000）。enabled=false（默认）冲突完全走现状路径（保留现场+冲突清单）；
+            #   解决失败/超时 → lane 保持 conflict 终态（不自动恢复）。
+            mergeAgent:
+              enabled: false
+              model: null
+              timeoutMs: 600000
+          # 验收证据（verify）：enabled=true 时引擎级挂 post-execute 证据捕获（<root>/verify/blobs 内容寻址 + ledger-<session>.jsonl）；
+          #   mode advisory（默认，只记录不拦截）/ enforce（显式启用则审计裁决拦截）；audit lane 经 evaluateAcEvidence 消费（DI 路径保留）；
+          #   显式 enabled:false 可关闭（关闭时捕获 hook 不挂、零运行时开销）。
+          verify:
+            enabled: true
+            mode: advisory
+          # 日志导出（log_export）：enabled=true 时注册 log_export 工具——模型可调用的只读事件流投影
+          #   （store.readBatch，零副作用）；支持 lane/type(前缀)/since 过滤 + format json/markdown + writeTo
+          #   落盘到引擎产物根（可审计）；显式 enabled:false 可关闭（关闭时工具不注册）。
+          logs:
+            enabled: true