@ifrankwang/openspec-agents 0.149.0 → 0.150.0

package/.mcp-server/cli.mjs

@@ -3284,6 +3284,37 @@ var require_utils = __commonJS(function(exports, module) {
     }
     return output.join("");
   }
+  function removeDotSegmentsRelative(path) {
+    if (path === "" || path[0] === "/") {
+      return removeDotSegments(path);
+    }
+    const segments = path.split("/");
+    const last = segments.length - 1;
+    const output = [];
+    let trailingDirectory = false;
+    for (let i = 0;i <= last; i++) {
+      const segment = segments[i];
+      if (segment === "." || segment === "..") {
+        if (segment === "..") {
+          if (output.length !== 0 && output[output.length - 1] !== "..") {
+            output.pop();
+          } else {
+            output.push("..");
+          }
+        }
+        trailingDirectory = i === last;
+      } else {
+        output.push(segment);
+      }
+    }
+    if (trailingDirectory && output[output.length - 1] !== "..") {
+      output.push("");
+    }
+    if (output.length === 0 || output[0] === "" || output[0].includes(":")) {
+      output.unshift(".");
+    }
+    return output.join("/");
+  }
   var HOST_DELIMS = { "@": "%40", "/": "%2F", "?": "%3F", "#": "%23", ":": "%3A" };
   var HOST_DELIM_RE = /[@/?#:]/g;
   var HOST_DELIM_NO_COLON_RE = /[@/?#]/g;
@@ -3544,6 +3575,7 @@ var require_utils = __commonJS(function(exports, module) {
     encodeFragment,
     escapePreservingEscapes,
     removeDotSegments,
+    removeDotSegmentsRelative,
     isIPv4,
     isUUID,
     normalizeIPv6,
@@ -3728,16 +3760,18 @@ var require_schemes = __commonJS(function(exports, module) {
 
 // node_modules/fast-uri/index.js
 var require_fast_uri = __commonJS(function(exports, module) {
-  var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, serializePathEncoding, normalizeQueryFragmentEncoding, encodeQuery, encodeFragment, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
+  var { normalizeIPv6, removeDotSegments, removeDotSegmentsRelative, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, serializePathEncoding, normalizeQueryFragmentEncoding, encodeQuery, encodeFragment, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
   var { SCHEMES, getSchemeHandler } = require_schemes();
   var VALID_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*$/u;
   var MALFORMED_SCHEME_ERROR = "URI scheme is malformed.";
-  function decodeValidScheme(scheme) {
-    const decodedScheme = unescape(String(scheme));
-    if (!VALID_SCHEME.test(decodedScheme)) {
+  var MALFORMED_HOST_ERROR = "URI host is malformed.";
+  var FORBIDDEN_DOMAIN_HOST_CHARACTER = /[\0-\x20"#/:<>?@[\\\]^`{|}\x7F]/u;
+  function validateScheme(scheme) {
+    const stringScheme = String(scheme);
+    if (!VALID_SCHEME.test(stringScheme)) {
       throw new TypeError(MALFORMED_SCHEME_ERROR);
     }
-    return decodedScheme;
+    return stringScheme;
   }
   function normalize(uri, options) {
     if (typeof uri === "string") {
@@ -3772,6 +3806,9 @@ var require_fast_uri = __commonJS(function(exports, module) {
     const resolvedSchemeHandler = getSchemeHandler(options && options.scheme || resolved.scheme);
     const resolvedHost = resolved.host;
     const resolvedHostIsIP = resolvedHost !== undefined && resolvedHost !== "" && (isIPv4(resolvedHost) || normalizeIPv6(resolvedHost).isIPV6);
+    if (hasForbiddenDomainHost(resolved, options || {}, resolvedSchemeHandler, resolvedHostIsIP)) {
+      throw new Error(MALFORMED_HOST_ERROR);
+    }
     canonicalizeHost(resolved, options || {}, resolvedSchemeHandler, resolvedHostIsIP);
     const encodedASCIIHost = resolvedHost && resolvedHost.indexOf("%") !== -1 && !/\P{ASCII}/u.test(resolvedHost);
     if (resolved.error && !encodedASCIIHost) {
@@ -3813,14 +3850,15 @@ var require_fast_uri = __commonJS(function(exports, module) {
           if (relative.path[0] === "/") {
             target.path = removeDotSegments(relative.path);
           } else {
-            if ((base.userinfo !== undefined || base.host !== undefined || base.port !== undefined) && !base.path) {
+            const baseHasAuthority = base.userinfo !== undefined || base.host !== undefined || base.port !== undefined;
+            if (baseHasAuthority && !base.path) {
               target.path = "/" + relative.path;
             } else if (!base.path) {
               target.path = relative.path;
             } else {
               target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative.path;
             }
-            target.path = removeDotSegments(target.path);
+            target.path = base.scheme === undefined && !baseHasAuthority && target.path[0] !== "/" ? removeDotSegmentsRelative(target.path) : removeDotSegments(target.path);
           }
           target.query = relative.query;
         }
@@ -3858,13 +3896,14 @@ var require_fast_uri = __commonJS(function(exports, module) {
     const options = Object.assign({}, opts);
     const uriTokens = [];
     if (component.scheme) {
-      component.scheme = decodeValidScheme(component.scheme);
+      component.scheme = validateScheme(component.scheme);
     }
     const schemeHandler = getSchemeHandler(options.scheme || component.scheme);
     if (schemeHandler && schemeHandler.serialize)
       schemeHandler.serialize(component, options);
     const hasAuthority = component.userinfo !== undefined || component.host !== undefined || component.port !== undefined;
-    const pathNoScheme = !options.skipEscape && component.scheme === undefined && !hasAuthority;
+    const schemelessReference = (component.scheme === undefined || options.reference === "suffix") && !hasAuthority;
+    const pathNoScheme = !options.skipEscape && schemelessReference;
     if (component.path !== undefined) {
       if (!options.skipEscape) {
         component.path = serializePathEncoding(component.path, pathNoScheme);
@@ -3873,7 +3912,7 @@ var require_fast_uri = __commonJS(function(exports, module) {
       }
     }
     if (options.reference !== "suffix" && component.scheme) {
-      component.scheme = decodeValidScheme(component.scheme);
+      component.scheme = validateScheme(component.scheme);
       uriTokens.push(component.scheme, ":");
     }
     const authority = recomposeAuthority(component);
@@ -3889,9 +3928,9 @@ var require_fast_uri = __commonJS(function(exports, module) {
     if (component.path !== undefined) {
       let s = component.path;
       if (!options.absolutePath && (!schemeHandler || !schemeHandler.absolutePath)) {
-        s = removeDotSegments(s);
+        s = schemelessReference && s[0] !== "/" ? removeDotSegmentsRelative(s) : removeDotSegments(s);
       }
-      if (pathNoScheme) {
+      if (schemelessReference) {
         s = serializePathEncoding(s, true);
       }
       if (authority === undefined && s[0] === "/" && s[1] === "/") {
@@ -3939,16 +3978,32 @@ var require_fast_uri = __commonJS(function(exports, module) {
     return hasMalformedPercentEncoding(matches[3]) || host !== undefined && !isIPLiteral(host) && hasMalformedPercentEncoding(host) || hasMalformedPercentEncoding(matches[6]) || hasMalformedPercentEncoding(matches[7]) || hasMalformedPercentEncoding(matches[8]);
   }
   function canonicalizeHost(parsed, options, schemeHandler, isIP) {
+    if (hasForbiddenDomainHost(parsed, options, schemeHandler, isIP)) {
+      parsed.error = parsed.error || MALFORMED_HOST_ERROR;
+      return true;
+    }
     if (!options.unicodeSupport && (!schemeHandler || !schemeHandler.unicodeSupport) && parsed.host && !isIPLiteral(parsed.host) && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP === false && nonSimpleDomain(parsed.host)) {
+      let url;
       try {
-        parsed.host = new URL("http://" + parsed.host).hostname;
+        url = new URL("http://" + parsed.host);
       } catch (e) {
         parsed.error = parsed.error || "Host's domain name can not be converted to ASCII: " + e;
         return true;
       }
+      if (!isHostOnlyURL(url)) {
+        parsed.error = parsed.error || MALFORMED_HOST_ERROR;
+        return true;
+      }
+      parsed.host = url.hostname;
     }
     return false;
   }
+  function hasForbiddenDomainHost(parsed, options, schemeHandler, isIP) {
+    return Boolean(parsed.host && isIP === false && !isIPLiteral(parsed.host) && (options.domainHost || schemeHandler && schemeHandler.domainHost) && FORBIDDEN_DOMAIN_HOST_CHARACTER.test(parsed.host));
+  }
+  function isHostOnlyURL(url) {
+    return url.username === "" && url.password === "" && url.port === "" && url.pathname === "/" && url.search === "" && url.hash === "" && url.hostname !== "";
+  }
   function parseWithStatus(uri, opts) {
     const options = Object.assign({}, opts);
     const parsed = {
@@ -4003,9 +4058,8 @@ var require_fast_uri = __commonJS(function(exports, module) {
       parsed.query = matches[7];
       parsed.fragment = matches[8];
       if (parsed.scheme !== undefined) {
-        const decodedScheme = unescape(parsed.scheme);
-        if (VALID_SCHEME.test(decodedScheme)) {
-          parsed.scheme = decodedScheme.toLowerCase();
+        if (VALID_SCHEME.test(parsed.scheme)) {
+          parsed.scheme = parsed.scheme.toLowerCase();
         } else {
           parsed.error = parsed.error || MALFORMED_SCHEME_ERROR;
           malformedScheme = true;
@@ -4033,7 +4087,7 @@ var require_fast_uri = __commonJS(function(exports, module) {
           malformedIPLiteral = hasIPLiteralBracket && (!bracketedIPLiteral || ipv6result.error === true);
           parsed.host = isIP ? ipv6result.host : ipv6result.host.toLowerCase();
           if (malformedIPLiteral) {
-            parsed.error = parsed.error || "URI host is malformed.";
+            parsed.error = parsed.error || MALFORMED_HOST_ERROR;
             malformedAuthorityOrPort = true;
           }
         } else {
@@ -4061,7 +4115,7 @@ var require_fast_uri = __commonJS(function(exports, module) {
         if (!isIP) {
           host = normalizePercentEncoding(host.toLowerCase());
         }
-        parsed.host = reescapeHostDelimiters(host, isIP);
+        parsed.host = isIP || options.scheme !== "null" ? reescapeHostDelimiters(host, isIP) : host;
       }
       if (!schemeHandler || schemeHandler && !schemeHandler.skipNormalize) {
         if (parsed.path) {
@@ -30575,7 +30629,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.149.0";
+var PKG_VERSION = "0.150.0";
 function buildMcpServer(worktree, opts = {}) {
   const mcp = new McpServer({ name: "openspec-agents", version: PKG_VERSION });
   for (const [name, spec] of Object.entries(TOOL_SPECS)) {

package/README.md

@@ -3,34 +3,49 @@
 ![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
 ![Built for OpenSpec](https://img.shields.io/badge/built%20for-OpenSpec-6b46c1.svg)
 
-> AI 写代码很快，但没有东西替你把关。
+`openspec-agents` 是 [OpenSpec](https://openspec.sh) 的配套插件，兼容 Claude Code / Codex / ZCode / DeepSeek Harness / OpenCode：提案阶段把标准钉得更死（澄清在前、改动范围与契约变更逐条确认），实施阶段由多 Agent 分工——写、查、验收、质量审查各由不同 Agent 担任，按生产级标准把控到收口。
 
-`openspec-agents` 是一组面向主流 AI 编码工具的插件，给 AI 写代码补上「可以交付」这道关卡：一个变更从「实现 → 检查 → 验收 → 收口」逐步推进，每一步都要通过校验才能往下走，通不过就退回去修；过程留痕，中断能接上。
+前提：项目正在使用 OpenSpec 管理需求。
 
-它补的是 [OpenSpec](https://openspec.sh) 变更从「规范写好了」到「代码真的没问题」之间的实施与把关环节。前提是你的项目在用 OpenSpec 管需求。
+| | |
+|---|---|
+| 适合 | 变更需要真正落进代码库、有验收标准、需通过检查、过程可追溯的团队与项目 |
+| 不适合 | 希望快速产出 demo、不走检查与验收的场景 |
+| 代价 | 比单个 AI 直接修改更慢，Token 消耗更高 |
+| 模型选型 | 实施用 flash 类模型，提案用旗舰模型 |
 
-## 你可能正遇到这些
+## 常见痛点
 
-- AI 一次改一大片，改完说「完成了」，但没人验证过它到底改对没有。
-- 一个共用逻辑被改动了，另一个入口还在用老写法，谁也没发现。
-- 出了问题想复盘，只翻得到一堆对话流水，看不出当时谁按什么标准放行的。
+- AI 一次改一大片，改完声称「完成了」——能编译、测试也通过，但其中夹带的空实现与伪成功未被发现。
+- 共用逻辑被改动后，其他调用入口仍在使用旧写法，无人察觉。
+- 出了问题想复盘，只能翻到大量对话记录，看不出当时按什么标准放行。
 
-## 它和你现在用的有什么不同
+## 与工具自带工作流的区别
 
-Claude Code 和 DeepSeek Harness 自带的工作流能力擅长**一次把很多活并行干完**。这个插件管的是另一件事，两者可以叠着用。
+Claude Code 和 DeepSeek Harness 自带的工作流能力擅长**并行完成大量独立任务**。这个插件解决的是另一件事，两者可以叠加使用。
 
 | | 工具自带的工作流 | 本插件 |
 |---|---|---|
-| 擅长 | 一次并行干完大量独立任务 | 一个变更按阶段推进，每步把关 |
-| 怎么放行 | 脚本里的判断 | 流程规则由程序强制：检查没做完、问题没闭环就不许提交通过 |
-| 换工具 | 各家私有 | 一套流程跨工具通用 |
-| 中断之后 | 进度绑在对话或某次运行上 | 进度记在仓库里，换会话、换工具都能接上 |
+| 擅长 | 并行完成大量独立任务 | 单个变更按阶段推进，逐层把关 |
+| 如何放行 | 由脚本中的判断决定 | 由程序强制：检查未完成、问题未闭环时无法以「通过」提交 |
+| 跨工具 | 各家私有 | 同一套流程跨工具通用 |
+| 中断之后 | 进度依附于对话或单次运行 | 进度记录在仓库中，换会话、换工具均可继续 |
+
+一句话：原生工作流负责把任务做完，这个插件负责判定产出是否达到生产级。
+
+## 局限
 
-一句话：原生工作流管「把活干完」，这个插件管「这次变更算不算通过」。
+使用前请先确认以下三条边界。
 
-## 从零跑起来
+**存量项目需要一次收敛成本。** 判据按理想状态定义（方法不超过 50 行、类职责单一、核心域不依赖框架、构建产物需忽略、覆盖率需达标），且工具检查覆盖全量代码——存量违规同样按原级别上报并阻塞。存量项目首次运行会暴露大量存量问题，只能逐个修复，或逐个走豁免裁定；裁定通过的会沉淀进项目级清单，后续变更不再重复阻塞。
 
-**前提**：项目已经在用 OpenSpec。没有的话先装上并初始化：
+**Java 之外只有通用规范。** 23 份 skill 中 10 份技术栈无关、11 份为 Java 后端配套（含具体构建与检查命令、ArchUnit 规则、Spotless / PMD / SonarQube 配置）。非 Java 项目审查照常执行，但编译、格式、静态分析、覆盖率这几项确定性检查没有现成命令，需自行补充一份技术栈 skill，否则只能按降级申报跳过。
+
+**架构规范只有 DDD 一套。** 包组织有两种等价的合法风格——四层分层（domain / application / infrastructure / interfaces）与六边形（内核 + 入站 / 出站适配器），采用哪种由项目声明，未声明时按四层认定。不按 DDD 组织的项目（例如 MVC + Service + DAO 直写）没有对应规范，会被判定为偏离规范并报出问题；项目已有自己的架构规范时以项目规范为准，但该规范需自行写入。
+
+## 快速开始
+
+项目还没用 OpenSpec 的话，先装上并初始化：
 
 ```bash
 npm install -g @fission-ai/openspec
@@ -69,6 +84,8 @@ dsh plugin --profile web add @ifrankwang/openspec-agents
 
 `web` 是 profile 名，换成你自己的（`~/.dsh/profiles/` 下的目录名）。装完重启该 profile；作用项目随当前会话所属项目自动确定，同一个 profile 下切换项目不必重装或改配置。编排工具需要在一个项目会话里使用。
 
+要求 DSH 0.2.1 及以上。子代理的角色提示词与工具集由 Agent Preset 承载，profile 需包含 web 应用 bundle（`desktop` / `web` 模板都满足）。子代理委派为异步：分派后等完成通知，再继续下一步。
+
 #### OpenCode
 
 要求 OpenCode 2.x（1.x 的插件接口不兼容）。
@@ -91,22 +108,23 @@ npm install -D @ifrankwang/openspec-agents
 
 首次加载时，插件会在项目 `.opencode/agents/` 下生成三个代理定义文件。这些文件带生成标记，插件**每次加载**都按当前版本重写；要自己改，先删掉文件里的生成标记。
 
-### 第二步：确认装上了
+### 第二步：确认安装成功
 
 重启后查看可用 skill 列表：`openspec-standard`、`orchestrator` 是插件自带的两个入口，它们和一批规范类 skill 一起出现在列表里，就说明插件已经生效。这些 skill 可以像命令一样唤起（DSH 里输入 `/` 即可看到并调用）。
 
-### 第三步：开始
+### 第三步：开始使用
 
 - 项目里还没提变更时，调用 `/openspec-standard`，把提案标准装进项目。
-- 用 OpenSpec 提一个变更（按 OpenSpec 的用法，在你的 AI 工具里把要做的事说清楚，生成 `openspec/changes/<变更名>/` 下的文档），然后调用 `/orchestrator {change-id}` 开始编排。`{change-id}` 就是那个目录名，`openspec list` 能看到当前有哪些变更。
+- 提变更用 OpenSpec 官方命令：`/openspec-propose {具体需求描述}`，生成 `openspec/changes/<变更名>/` 下的文档；装过提案标准后，这些文档会按更严的标准产出。
+- 然后调用 `/orchestrator {change-id}` 开始编排。`{change-id}` 就是那个目录名，`openspec list` 能看到当前有哪些变更。
 
 > 不同工具里 skill 的呈现形式可能不同，以各工具实际显示为准。
 
-### 默认由 AI 自行拍板
+### 默认无人值守
 
 各安装方式**默认都开启无人值守**：流程里需要人拍板的环节（方案怎么选、无法自动验证的部分）由编排 AI 自行决断，不会停下来问你——**审查和门禁照常跑，变的只是「要不要来问你」**。希望它在这些地方先问你，让它关掉无人值守模式即可。
 
-### 顺手加两行进 `.gitignore`
+### 将以下两行加入 `.gitignore`
 
 ```
 .worktree/
@@ -115,32 +133,6 @@ openspec/states/
 
 两者都不该进版本库：前者是变更（以及独立审查）的独立工作副本，后者是流程进度。
 
-## 它替你守住什么
-
-- **分工协作**：不再是单个 AI 从头写到尾、写完自己说没问题。完整模式下，实现、检查、验收、质量审查是彼此分开的角色；精简模式把确定性检查交给开发者执行，再由一个审查者合并复核。
-- **每一步都要过校验**：完整模式下，实现完先过工具检查，再走独立验收，最后过多个维度的质量审查，结论不通过就退回修复。流程规则由程序强制——检查没做完、问题没闭环，就不可能以「通过」提交；至于质量判断本身，仍由承担该环节的审查角色给出。
-- **问题跟到底**：变更编排里，审查发现的问题会一直挂在变更上，要么修好，要么走豁免流程由报出该问题的审查者裁定通过，否则不允许继续推进。
-- **写隔离**：变更在独立分支和独立工作副本里做，收口前你的基准分支上看不到这些改动。
-- **中断能接上**：进度记在仓库里，问一句「现在跑到哪了」就能看到；关掉工具、隔一天、换个工具，都能从上次的位置继续。
-- **规范驱动**：直接消费 OpenSpec 的提案、规格、设计、任务清单，流程与规范一一对应。
-
-初始化编排时选流程模式，**默认是精简模式**：精简模式把确定性检查交给开发者执行、审查者分级复验，小改动不必走全套；完整模式开头多一道方案预检，验收也拆得更细。
-
-## 内置的规范库
-
-插件自带 23 份 skill（含两个流程入口），装了就有，不用自己写提示词；审查的 AI 会按当前任务需要自动挂上对应的一组。
-
-**两个入口**
-
-- `orchestrator` —— 编排准则，主代理按它分派子代理、推进流程。
-- `openspec-standard` —— 提案标准初始化。
-
-**10 份通用规范**：DDD 分层与六边形、REST 接口约定、数据库设计约定、安全审查基线、确定性质量门、测试设计、技术债识别、架构演进审查、API 自动化测试、隔离环境清理。
-
-**11 份 Java 后端配套**：在通用规范之上补齐 Java / Spring 的实现细节 —— Lombok、日志与命名约定、REST 接口的 Java 实现、MyBatisPlus 与 Flyway、DDD 的 Java 实现与 ArchUnit 规则、Maven / Spotless / PMD / SonarQube 质量门、工具规则改进、Java 开发实践、Java 安全实现、Java 性能与可维护性、Java 技术债形态。
-
-Java 后端项目会自动带上配套那套；其它语言目前只有通用规范生效，具体的构建与检查命令由你项目的规范补充。
-
 ## 提案标准化
 
 OpenSpec 官方默认的流程是 `proposal → specs → design → tasks`，给出文档骨架与写作要求。这套标准在它前面加一道澄清与确认关，并把改动范围、契约变更、文档语言钉得更死。
@@ -157,10 +149,60 @@ OpenSpec 官方默认的流程是 `proposal → specs → design → tasks`，
 | 任务划分 | 分组 + 每条带验证方式 | 追加：每组必须有真实代码改动（禁止「收尾组」凑数）、测试跟着实现同组、只覆盖本仓库 |
 | 归档 | 官方归档命令本身会同步主规格 | 追加写作纪律：主规格只写终态，不留「原 X 改为 Y」；废弃项显式删除并补 REMOVED；同语义合并去重 |
 
-用法：在目标项目的普通会话里调用 `/openspec-standard`（不要在被编排流程占用的会话里调用，那种会话不能改文件）。它会先检查项目有没有 `openspec/` 目录，再把标准写进去。
+**用法**：在目标项目的普通会话里调用 `/openspec-standard`（不要在被编排流程占用的会话里调用，那种会话不能改文件）。它会往项目写入 `openspec/config.yaml`（指定 `spec-driven-standard` schema）与 `openspec/schemas/spec-driven-standard/`。
+
+装好之后提变更不必换命令，仍走 OpenSpec 官方用法：调用 `/openspec-propose {具体需求描述}`，生成的 proposal / specs / design / tasks 就会按这套标准产出，再由 `/orchestrator {change-id}` 接手实施与把关。
 
 已经装过标准的项目重跑就是升级：标准更新到插件当前版本，你自己加的规则条目和项目背景会保留。
 
+## 质量把关机制
+
+「生产级」不是靠提示词要求的，而是逐层校验出来的。
+
+**审查分工**
+
+```
+完整模式  方案预检 → 实现 → 工具检查 → 独立验收 → 五维质量审查 → 收口
+精简模式  实现 → 合并审查 → 收口
+```
+
+最终判定不由实现者自己作出。完整模式下，检查、验收、质量审查由彼此独立的角色承担；精简模式由开发者执行确定性检查，再由一名审查者独立复核。
+
+**工具与 AI 的分工**
+
+确定性检查全部交给工具执行：编译、代码格式、架构约束、静态分析、单元测试与覆盖率、深度扫描，以及质量工具配置有没有被弱化。AI 审查只负责工具覆盖不到的部分——业务行为是否真实生效、关键数据是否真的落库、测试断言有没有放水、设计与规则边界是否站得住，并把其中可工具化的发现反过来沉淀成规则。判据锚在 skill 上，不是让模型现场发挥，所以非旗舰模型（flash 类）的产出下限同样有保障。
+
+**通过标准**
+
+- **五级定级**：Critical / High / Medium / Low / Info，各级判例锚定规范 skill；Info 仅为建议，Low 及以上未修复不得推进。
+- **问题闭环**：审查报出的问题挂在变更上，修复后由报出该问题的审查者复核通过方为终结；确实无法修复的提交豁免申请，由同一审查者裁定，被驳回则退回重修。
+- **程序强制**：检查未完成、问题未闭环时，无法以「通过」提交——由工具拦截，而非依赖提示词约束。
+- **禁止规避**：压制注解、关闭规则、修改扫描平台状态一律视为豁免申请，须写明理由并接受裁定；同一问题修复未过两次，须先完成根因分析再修改。
+- **规则沉淀**：可由工具检出的问题，要求同时提交业务问题与规则草案，将本次判定口径沉淀为后续的自动拦截规则。
+
+**其他特性**
+
+- **变更隔离**：变更在独立分支与独立工作副本中进行，收口前基准分支上看不到这些改动。
+- **可续跑**：进度记录在仓库中，查询当前状态即可恢复；关闭工具、跨天、更换工具都能从上次位置继续。
+- **规范驱动**：直接消费 OpenSpec 的提案、规格、设计与任务清单，流程与规范一一对应。
+
+初始化编排时选择流程模式，**默认为精简模式**：精简模式下小改动不必走全套流程；完整模式在开头增加一道方案预检，验收也拆得更细。
+
+## 内置的规范库
+
+插件自带 23 份 skill（含两个流程入口），安装后即可使用，无需自行编写提示词；审查 AI 会按当前任务自动加载对应的一组，作为判据的**最低基准**——审查者还需结合自身领域知识扩展覆盖，不限于清单所列条目。
+
+**两个入口**
+
+- `orchestrator` —— 编排准则，主代理按它分派子代理、推进流程。
+- `openspec-standard` —— 提案标准初始化。
+
+**10 份通用规范**：DDD 分层与六边形、REST 接口约定、数据库设计约定、安全审查基线、确定性质量门、测试设计、技术债识别、架构演进审查、API 自动化测试、隔离环境清理。
+
+**11 份 Java 后端配套**：在通用规范之上补齐 Java / Spring 的实现细节 —— Lombok、日志与命名约定、REST 接口的 Java 实现、MyBatisPlus 与 Flyway、DDD 的 Java 实现与 ArchUnit 规则、Maven / Spotless / PMD / SonarQube 质量门、工具规则改进、Java 开发实践、Java 安全实现、Java 性能与可维护性、Java 技术债形态。
+
+Java 后端项目会自动带上配套那套；其它语言目前只有通用规范生效，具体的构建与检查命令由你项目的规范补充。
+
 ## 独立审查会话
 
 除了绑定变更的编排，插件也支持不绑定任何变更的独立代码审查：对一个 PR 的改动区间、或整个代码库做一次完整审查。
@@ -173,7 +215,7 @@ OpenSpec 官方默认的流程是 `proposal → specs → design → tasks`，
 
 审查在独立工作副本里进行。`fix` 模式全部通过后把工作分支合并回目标分支并清理环境；`none` 模式不合并，直接销毁工作环境并按严重级别、维度、文件位置归并给出审查结果。
 
-## 它会往你仓库里写什么
+## 对仓库的写入范围
 
 编排流程只碰这几处，全在你的仓库内：
 
@@ -185,16 +227,7 @@ OpenSpec 官方默认的流程是 `proposal → specs → design → tasks`，
 
 变更的全部任务组完成后，才会把这条分支合并回基准分支，随后自动删掉工作副本和分支。合并前如果基准分支已经往前走了，插件先比对两边改动：只有文档、规划文件或版本号这类无害变化时直接合并；有实质冲突时退回做一次收尾回归，通过后才合并。
 
-**中途想放弃**：删掉工作副本和 `change/<变更号>` 分支即可，基准分支上不会留下这个变更的任何代码。
-
-## 适用场景与代价
-
-| | |
-|---|---|
-| 适合 | 一个变更要真正落进代码库、有验收标准、要过几道检查、过程要能审计，可能跨天甚至跨工具的团队与项目 |
-| 代价 | 比单个 AI 直接改更慢，Token 消耗更高 |
-
-如果你愿意用一点成本换取稳定、可复现、可审计的实施过程，这个项目就是为你准备的。
+**中途放弃**：删除工作副本与 `change/<变更号>` 分支即可，基准分支不会留下该变更的任何代码。
 
 ## 开发
 

package/assets/skills/orchestrator/SKILL.md

@@ -42,7 +42,7 @@ capabilities: ["orchestrator"]
 
 ## 行为准则
 
-- 每次子代理返回后，调用状态查询工具获取权威「下一步」指令并严格遵循；推进被拦时按工具给出的阻塞原因与修复建议处理，不自行推断其他动作
+- 每次子代理返回后，调用状态查询工具获取权威「下一步」指令并严格遵循；推进被拦时按工具给出的阻塞原因与修复建议处理，不自行推断其他动作。DSH 形态下「返回」指收到子代理完成通知，不是分派工具的即时返回（见「分派范式」的 DSH 异步委派）
 - 分派/推进决策一律以工具返回为准：工具已给出明确分派指令时直接分派，不得先读状态文件交叉验证；仅门禁拒绝或工具给出修复建议时才读取状态文件核对
 - 分派子代理前先查询状态确认当前阶段/层，确保不跳阶段或错层分派；工具视图呈现 worktree 未就绪时不得分派
 - 不过度沟通：任务组内部不停下来向用户汇报，持续执行直到阻塞或完成
@@ -95,6 +95,14 @@ full 模式 verify_quality 以 5 个逻辑身份并行审查：同一物理审
 
 不包含任何 task/issue 明细、文件清单、执行边界具体值等动态内容——一切交给状态查询工具。
 
+### DSH 异步委派
+
+DSH 0.2.1 起子代理委派为异步：`openspec_developer` / `openspec_reviewer` 调用后只返回子任务 id，子代理结束时会收到完成通知。
+
+- 分派后不要立即查状态、不要重复分派同一角色；收到该子代理的完成通知后再查状态推进
+- 并排分派的多个子代理各自完成、各自通知，全部到齐后再进入下一步
+- 通知里的最终回答是子代理自述，权威状态仍以状态查询工具为准
+
 ## 无人值守行为约定
 
 无人值守模式下，所有需拍板事项由你依据工具返回与已加载 skill 的规范自行裁决，**不向用户提问**：