@joekytc/dsh-swarm 0.3.1 → 0.3.2

package/lib/domain/ocr-review.d.ts

@@ -7,8 +7,12 @@ export interface OcrArgsInput {
     to?: string;
     commit?: string;
     paths?: string[];
+    /** 业务上下文，托管评审时提升评审质量（仅 managed 分支透传）。 */
+    background?: string;
 }
-/** 构造 OCR CLI 参数：preview/rule 走 delegate，managed 走 review 并恒带 JSON 输出。 */
+/** 构造 OCR CLI 参数：preview/rule 走 delegate，managed 走 review。
+ * preview 默认输出 text，必须显式 --format json 才能拿到可解析输出；
+ * managed 恒带 --audience agent（agent 场景标准参数，抑制 progress 输出）。 */
 export declare function buildOcrArgs(sub: OcrSub, a: OcrArgsInput): string[];
 /** 预览结果归一化结构。 */
 export interface PreviewResult {
@@ -23,7 +27,7 @@ export interface PreviewResult {
     }[];
     mergeBase: string | null;
 }
-/** 解析 delegate preview 的 JSON 输出，失败或结构异常时回退 unknown。 */
+/** 解析 delegate preview 的 JSON 输出（官方字段 reviewable_files/excluded_files/exclude_reason），失败或结构异常时回退 unknown。 */
 export declare function parsePreviewJson(stdout: string): PreviewResult;
 /** 托管评审结果归一化结构。 */
 export interface ManagedResult {

package/lib/domain/ocr-review.js

@@ -1,11 +1,17 @@
-/** 构造 OCR CLI 参数：preview/rule 走 delegate，managed 走 review 并恒带 JSON 输出。 */
+/** 构造 OCR CLI 参数：preview/rule 走 delegate，managed 走 review。
+ * preview 默认输出 text，必须显式 --format json 才能拿到可解析输出；
+ * managed 恒带 --audience agent（agent 场景标准参数，抑制 progress 输出）。 */
 export function buildOcrArgs(sub, a) {
     if (sub === 'preview') {
-        const args = ['delegate', 'preview'];
-        if (a.from)
-            args.push('--from', a.from);
-        if (a.to)
-            args.push('--to', a.to);
+        const args = ['delegate', 'preview', '--format', 'json'];
+        if (a.commit)
+            args.push('--commit', a.commit);
+        else if (a.from || a.to) {
+            if (a.from)
+                args.push('--from', a.from);
+            if (a.to)
+                args.push('--to', a.to);
+        }
         if (a.repo)
             args.push('--repo', a.repo);
         return args;
@@ -22,7 +28,9 @@ export function buildOcrArgs(sub, a) {
         if (a.to)
             args.push('--to', a.to);
     }
-    args.push('--format', 'json');
+    args.push('--format', 'json', '--audience', 'agent');
+    if (a.background)
+        args.push('--background', a.background);
     return args;
 }
 /** 解析失败的兜底结果。 */
@@ -37,7 +45,7 @@ function pathOf(el) {
 function asArray(v) {
     return Array.isArray(v) ? v.filter(isRecord) : [];
 }
-/** 解析 delegate preview 的 JSON 输出，失败或结构异常时回退 unknown。 */
+/** 解析 delegate preview 的 JSON 输出（官方字段 reviewable_files/excluded_files/exclude_reason），失败或结构异常时回退 unknown。 */
 export function parsePreviewJson(stdout) {
     let obj;
     try {
@@ -51,8 +59,8 @@ export function parsePreviewJson(stdout) {
     const mergeBase = obj.merge_base ?? obj.mergeBase;
     return {
         mode: String(obj.mode ?? 'unknown'),
-        files: asArray(obj.files).map((el) => ({ path: pathOf(el), status: String(el.status ?? '') })),
-        excluded: asArray(obj.excluded).map((el) => ({ path: pathOf(el), reason: String(el.reason ?? '') })),
+        files: asArray(obj.reviewable_files).map((el) => ({ path: pathOf(el), status: String(el.status ?? '') })),
+        excluded: asArray(obj.excluded_files).map((el) => ({ path: pathOf(el), reason: String(el.exclude_reason ?? '') })),
         mergeBase: mergeBase == null ? null : String(mergeBase),
     };
 }
@@ -68,7 +76,8 @@ export function parseManagedJson(stdout) {
     if (!isRecord(obj))
         return { status: 'unknown', comments: [] };
     const comments = asArray(obj.comments).map((el) => {
-        const rawLine = el.line ?? el.startLine;
+        // 官方 schema 行号字段为 snake_case start_line，line/startLine 仅作容错别名
+        const rawLine = el.start_line ?? el.line ?? el.startLine;
         const line = Number(rawLine);
         const message = String(el.content ?? el.message ?? el.body ?? '');
         return {

package/lib/routes/kanban-http.js

@@ -1,3 +1,4 @@
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
 import { execFile } from 'node:child_process';
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -72,13 +73,17 @@ const OCR_WIRE_DEGRADED = '未能从 dsh 解析该提供方的接入信息（bas
  * 从宿主设置解析所选提供方的接入信息（baseUrl/协议/apiKey）。
  * 事实核查结论（实现期探查）：llm 服务的公开 API 不暴露连接事实，但同进程可经
  * settings 服务的 describe() 读到模型适配器的 provider profile——形如
- * { providers: { <id>: { baseURL, api, apiKey | apiKeyEnv } } }（apiKeyEnv 指向进程环境变量名）。
+ * { providers: { <id>: { baseURL, api, apiKey | apiKeyEnv } } }（apiKeyEnv 指向凭据引用名）。
+ * 踩坑：apiKeyEnv 名下的 key 不一定在进程 env——Models 页写入的凭据存在
+ * credentials 服务的 managed store（ctx.credentials）里；解析顺序须先进程 env、
+ * 再 ctx.credentials.resolve（env → managed store → $DSH_HOME/.env，per-call 不缓存）。
  * 命中 profile 但字段不全时跳过该 descriptor 继续尝试下一个（多 descriptor 场景勿误降级），
  * 绝不回传半套配置；全部不合才返回 null 走降级。apiKey 只透传给 ocr config，不落日志。
  */
-function resolveDshProviderAccess(ctx, providerId) {
+async function resolveDshProviderAccess(ctx, providerId) {
     try {
         const settings = ctx.get('settings');
+        const creds = ctx.get('credentials');
         const descriptors = settings?.describe?.() ?? [];
         for (const d of descriptors) {
             const providers = d.value?.providers;
@@ -89,8 +94,13 @@ function resolveDshProviderAccess(ctx, providerId) {
             const api = typeof profile.api === 'string' ? profile.api : '';
             const protocol = api.startsWith('openai') ? 'openai' : api.includes('anthropic') ? 'anthropic' : '';
             let apiKey = typeof profile.apiKey === 'string' ? profile.apiKey : '';
-            if (!apiKey && typeof profile.apiKeyEnv === 'string')
+            if (!apiKey && typeof profile.apiKeyEnv === 'string') {
                 apiKey = process.env[profile.apiKeyEnv] ?? '';
+                if (!apiKey && creds?.resolve) {
+                    const r = await creds.resolve(credentialRef(profile.apiKeyEnv));
+                    apiKey = r?.value ?? '';
+                }
+            }
             if (baseUrl && protocol && apiKey)
                 return { baseUrl, protocol, apiKey };
             continue; // 字段不全：换下一个 descriptor，勿在此误降级
@@ -330,7 +340,7 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                         json(res, 200, { ok: false, log: INSTALL_GUIDANCE });
                         return;
                     }
-                    const access = resolveDshProviderAccess(ctx, providerId);
+                    const access = await resolveDshProviderAccess(ctx, providerId);
                     if (!access) {
                         json(res, 200, { ok: false, log: OCR_WIRE_DEGRADED });
                         return;

package/lib/tools/ocr-review-tools.js

@@ -28,6 +28,7 @@ export function buildOcrReviewTool(deps) {
             to: { type: 'string', description: '目标分支/引用（range 模式，默认 HEAD）' },
             commit: { type: 'string', description: '单次提交审查' },
             paths: { type: 'array', items: { type: 'string' }, description: 'rule 子命令的文件路径列表' },
+            background: { type: 'string', description: '业务上下文，托管评审时提升评审质量' },
         },
         output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: String(v) }] },
         async execute(args) {
@@ -42,18 +43,24 @@ export function buildOcrReviewTool(deps) {
                 throw new Error("ocr_review: sub='rule' requires non-empty paths (file path list)");
             if (args.sub === 'managed' && !args.commit && !args.from)
                 throw new Error("ocr_review: sub='managed' requires commit or from (base ref)");
-            const res = await runOcrFn(buildOcrArgs(args.sub, { repo: args.repo, from: args.from, to: args.to, commit: args.commit, paths: args.paths }), { cwd: deps.cwd?.() ?? process.cwd(), timeoutMs: 600_000 });
-            if (res.error && !res.stdout)
-                throw new Error(`ocr_review: ${res.error} ${res.stderr.slice(0, 500)}`.trim());
+            // 托管评审走 ocr 自带 LLM（官方预算 15min×2 rounds），超时须远大于 preview/rule 的本地 git 操作
+            const timeoutMs = args.sub === 'managed' ? 2_400_000 : 600_000;
+            const res = await runOcrFn(buildOcrArgs(args.sub, { repo: args.repo, from: args.from, to: args.to, commit: args.commit, paths: args.paths, background: args.background }), { cwd: deps.cwd?.() ?? process.cwd(), timeoutMs });
+            // 失败不抛错：结果附 error 摘要（error + stderr 前 500 字符），模型拿得到部分结果与原因后自行降级/重试
+            const errSummary = res.error ? `${res.error} ${res.stderr.slice(0, 500)}`.trim() : '';
             if (args.sub === 'preview') {
                 const preview = parsePreviewJson(res.stdout);
+                const errorPart = errSummary ? { error: errSummary } : {};
                 if (shouldSuggestManaged(preview.files.length)) {
-                    return JSON.stringify({ ...preview, suggestion: `文件较多（N>${SUGGEST_MANAGED_FILES}），可在配置面板切换托管模式` });
+                    return JSON.stringify({ ...preview, ...errorPart, suggestion: `文件较多（N>${SUGGEST_MANAGED_FILES}），可在配置面板切换托管模式` });
                 }
-                return JSON.stringify(preview);
+                return JSON.stringify({ ...preview, ...errorPart });
             }
-            if (args.sub === 'rule')
+            if (args.sub === 'rule') {
+                if (errSummary)
+                    return JSON.stringify({ error: errSummary });
                 return res.stdout.slice(0, 8000);
+            }
             const report = parseManagedJson(res.stdout);
             if (report.status !== 'completed' && res.error)
                 return JSON.stringify({ ...report, message: res.error });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joekytc/dsh-swarm",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "A governed swarm of six specialist DSH agents (orchestrator, planner, knowledge-base bridge, developer and two reviewers) that turns a requirement into a strict phase pipeline with machine-verified delivery evidence, review-gated merges, a full audit-log event stream and a live kanban tab; design inspired by the Hermes Agent kanban",
   "license": "MIT",
   "author": "joekytc",
@@ -48,6 +48,10 @@
     },
     "./package.json": "./package.json"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && npm run build:client",
     "typecheck": "tsc -p tsconfig.json --noEmit",
@@ -59,6 +63,7 @@
     "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
     "@deepseek-ai/dsh-api-session-controller": "^0.1.2-rc.1",
     "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-credentials": "^0.1.2-rc.1",
     "@deepseek-ai/dsh-persona": "^0.1.2-rc.1",
     "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
     "@deepseek-ai/dsh-tool-bash": "^0.1.2-rc.1",

package/personas/kanban-d/agent.cordis.yml

@@ -56,7 +56,6 @@
       creating tasks, or wiki_write. Do NOT run sub-workflows or ralph loops inside a card.
       c. Verify before claiming done (verification-before-completion): run `npx vitest run` + build +
       typecheck, and confirm your diff, before complete. Use using-git-worktrees for isolation.
-      d. Before submitting to DT, self-review your diff with open-code-review (delegation) to reduce rework.
       7. Commit convention: `<type>: [AI-GEN] <one-line concise description>` (type in
       feat/fix/chore/docs/refactor/test/perf/ci...). Workflow: worktree isolated branch →
       implement + verify → [AI-GEN] commit → (optionally push the feature branch). Do NOT merge

package/personas/kanban-dt/agent.cordis.yml

@@ -33,9 +33,10 @@
       yourself → classify findings by severity (Critical/High must be reported, Medium with
       context, Low dropped by default). Managed = call ocr_review{sub:'managed',
       from:<TARGET_BRANCH>, to:<branch>} for normalized findings in one shot (<branch> = D's
-      feature branch from the parent handoff metadata.branch); silently fall back to the
-      delegate flow when status is not completed or the tool returns managed-not-configured
-      guidance. When ocr is not installed the tool returns install guidance (installable
+      feature branch from the parent handoff metadata.branch; you may pass background with a
+      one-line business context distilled from the spec card / task description); silently
+      fall back to the delegate flow when status is not completed or the tool returns
+      managed-not-configured guidance. When ocr is not installed the tool returns install guidance (installable
       from the GUI config panel); in chain scenarios kanban_block('review-tool-unavailable')
       and note the GUI install option in the reason. Standalone review mode (no bound chain
       task): review user-specified local dirs, branch ranges (--from/--to), single commits,

package/personas/persona-d.md

@@ -24,5 +24,4 @@
       禁止子代理批准规格/建卡/wiki_write。卡内禁止跑子工作流或 ralph 循环。
    c. 完成前先验证（verification-before-completion）：complete 前跑 `npx vitest run` + build +
       typecheck，并核对你的 diff。用 using-git-worktrees 隔离工作区。
-   d. 提交 DT 前，用 open-code-review（delegation）自审 diff，减少返工轮次。
 7. commit 规范：`<type>: [AI-GEN] <一句话简洁描述>`（type 取 feat/fix/chore/docs/refactor/test/perf/ci...）。工作流：worktree 隔离分支 → 实现+验证 → [AI-GEN] commit →（可选推 feature 分支）。禁止合并回 TARGET_BRANCH / 推 TARGET_BRANCH——由 DT 通过后 system 合入。

package/personas/persona-dt.md

@@ -6,7 +6,7 @@
 
 1. 实证校验 6 项（全部通过才 pass）：①测试真实运行 exit 0（在 D 仓库内实际跑）；②build/typecheck/lint 通过（语言相关，无则豁免）；③diff 非空（相对 base 有真实变更）；④规格对齐（覆盖 solution/testing，不越 out_of_scope）；⑤git 产物证据存在且可核对（changed_files/commit_hash/push 分支）；⑥open-code-review 评审（critical/high 已修复或有说明）。
 2. 你有只读硬护栏（ToolGuard 拦截 tracked source 写入 / git mutation / 含写标记 bash / run_code 写源码）；不注入 git 凭据；sandbox=workspace-write。绝不改源码；验证命令（npm test/build、tsc --noEmit、eslint、git show/log、ocr review）放行。
-3. 评审引擎由配置面板 reviewEngine.mode 决定（默认委托）：①委托 = 调 ocr_review{sub:'preview'} 获取评审范围 → ocr_review{sub:'rule'} 获取各文件评审规则 → 自行 git diff 逐文件深入评审 → 按严重级归类（Critical/High 必报、Medium 带上下文、Low 默认丢弃）；②托管 = 调 ocr_review{sub:'managed', from:<TARGET_BRANCH>, to:<branch>} 一次出归一化 findings（branch 取 D 交接 metadata.branch），status 非 completed 或返回托管未配置指引时静默改走委托流程。
+3. 评审引擎由配置面板 reviewEngine.mode 决定（默认委托）：①委托 = 调 ocr_review{sub:'preview'} 获取评审范围 → ocr_review{sub:'rule'} 获取各文件评审规则 → 自行 git diff 逐文件深入评审 → 按严重级归类（Critical/High 必报、Medium 带上下文、Low 默认丢弃）；②托管 = 调 ocr_review{sub:'managed', from:<TARGET_BRANCH>, to:<branch>} 一次出归一化 findings（branch 取 D 交接 metadata.branch；可带 background 传业务上下文，从规格卡/任务描述提炼一句话背景），status 非 completed 或返回托管未配置指引时静默改走委托流程。
 4. wiki 只读 + 写仅限 `projects/<repoSlug>/<chain>/review/` 评审命名空间（repoSlug 由系统按链工作区派生；写评审结论/证据链，不替代 W 的产物同步）。
 5. 评审结论写进 kanban_complete 的交接 metadata.review_evidence = { verdict: 'pass'|'fail', issues: [...], test/build/typecheck/lint/diff/git/openCodeReview/reviewPage }：
    - pass = 六项校验全过 → 系统推进 W3；
@@ -15,7 +15,7 @@
 
 ## open-code-review（ocr）评审引擎（双模）
 - 评审引擎由配置面板 reviewEngine.mode 决定（默认委托）：委托 = 调 ocr_review{sub:'preview'} 获取评审范围 → ocr_review{sub:'rule'} 获取各文件评审规则 → 自行 git diff 逐文件深入评审 → 按严重级归类（Critical/High 必报、Medium 带上下文、Low 默认丢弃）。
-- 托管 = 调 ocr_review{sub:'managed', from:<TARGET_BRANCH>, to:<branch>}（branch 取 D 交接 metadata.branch）一次出归一化 findings；status 非 completed 或返回托管未配置指引时静默改走委托流程。
+- 托管 = 调 ocr_review{sub:'managed', from:<TARGET_BRANCH>, to:<branch>}（branch 取 D 交接 metadata.branch；可带 background 传业务上下文，从规格卡/任务描述提炼一句话背景）一次出归一化 findings；status 非 completed 或返回托管未配置指引时静默改走委托流程。
 - ocr 未安装时工具自动返回中文安装指引（可在 GUI 配置面板安装）；链上场景按规则 kanban_block('review-tool-unavailable') 并在 reason 注明 GUI 可安装。
 
 ## 独立评审模式