dsh-github-flow 0.6.0 → 0.7.1

package/lib/github-service.d.ts

@@ -3,7 +3,7 @@
  *
  * 为什么需要这个文件：README 教生态插件这样复用本插件的能力——
  *   export const inject = ['github']
- *   export function apply(ctx) { await ctx.github.checkAuth() }
+ *   export async function apply(ctx) { await ctx.github.checkAuth() }
  * 但在此之前项目里没有任何 `declare module` 声明合并，消费方拿到的 `ctx.github`
  * 类型是 unknown，照文档写会直接编译不过，也没有任何自动补全。
  * 官方每个服务包（如 @deepseek-ai/dsh-workspace、dsh-commands）都做这件事，这里补齐。

package/lib/main.d.ts

@@ -1,29 +1,103 @@
+import type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
 import { GhExecutor } from './executor.js';
 import './github-service.js';
-import type { PluginConfig } from './types.js';
 export declare const name = "dsh-github-flow";
 /**
- * 核心服务依赖声明
+ * 服务依赖声明：只声明唯一的硬依赖 `tools`。
  *
- * 必须显式声明 webServer 与 workspaceRegistry：
- * 在 Cordis 依赖隔离机制下，只有在 inject 显式声明的服务，当前插件作用域 ctx 才能持有
- * ctx.webServer 与 ctx.workspaceRegistry 引用，进而注册 Web UI 所需的后端 API 路由。
+ * 为什么其余三个服务降级为可选（`ctx.inject` 等待）：
+ * - `webServer` 由 `@deepseek-ai/dsh-web-app` 组合提供。`dsh-tui` 与纯 CLI profile 只装
+ *   `dsh-base`，没有这个服务——写成硬依赖会让插件在这些 profile 里**永久 PENDING**，
+ *   用户一个工具都拿不到（README 明确支持 CLI 安装）。
+ * - `commands` 由 `dsh-commands` 提供，同样不保证所有组合都有。
+ *
+ * cordis 的语义是：`inject` 里的服务缺席 ⇒ 插件不激活。因此"声明了就必须真存在"，
+ * 声明硬依赖却按可选写 `if (ctx.X)` 是最坏组合：既让可选服务变成了硬门槛，
+ * 又让降级分支永远走不到。
+ */
+export declare const inject: readonly ['tools'];
+/**
+ * 本插件向宿主提供的服务名。
+ * cordis loader 读取该元数据（registry.d.ts），与 `ctx.provide('github', …)` 必须同名。
  */
-export declare const inject: readonly ['tools', 'commands', 'webServer', 'workspaceRegistry'];
-export type Config = PluginConfig;
+export declare const provide = "github";
 /**
- * 符合 Standard Schema / Cordis Loader 契约的 Config 运行时校验规范
+ * 插件配置 Schema（Schemastery）。
+ *
+ * 与旧的手写 `'~standard'.validate()` 相比，这里拿到的是**真校验**：类型不符直接抛
+ * `ValidationError`（旧实现对脏配置静默回落到默认值，配错了永远不报错）。
+ * 未知键仍原样透传，与旧行为一致。
+ *
+ * `.volatile()` 的三个字段是「运行期可热改、不触发插件 reload」的稳定引用：
+ * 读取点必须走 `.get()`，否则拿到的是引用对象本身（详见 `resolvePluginConfig`）。
+ *
+ * 为什么 `checkUpdate` 刻意**不** volatile：`UpdateChecker.enabled` 是构造期只读字段，
+ * 它同时决定轮询定时器与启动横幅是否建立。标成 volatile 只会得到「配置改了、行为没变」
+ * 的假热更新；让它保持普通字段，改动时插件整体重载，语义才是对的。
  */
-export declare const Config: {
-    '~standard': {
-        version: number;
-        vendor: string;
-        validate(value: unknown): {
-            value: PluginConfig;
-        };
-    };
-};
-export declare function apply(ctx: any, config?: PluginConfig): void;
+declare const ConfigSchema: Schema<Schemastery.ObjectS<NoInfer<{
+    ghPath: Schema<string, string, "defined">;
+    defaultTimeoutMs: Schema<number, number, "volatile-defined">;
+    maxOutputChars: Schema<number, number, "volatile-defined">;
+    maxOutputBytes: Schema<number, number, "plain">;
+    cacheTtlMs: Schema<number, number, "defined">;
+    defaultListLimit: Schema<number, number, "volatile-defined">;
+    checkUpdate: Schema<boolean, boolean, "defined">;
+    updateCheckIntervalMs: Schema<number, number, "defined">;
+    registryUrl: Schema<string, string, "plain">;
+    agentEnvInjection: Schema<boolean, boolean, "defined">;
+    proxyUrl: Schema<string, string, "plain">;
+    toolsets: Schema<string[], string[], "plain">;
+    read_only: Schema<boolean, boolean, "plain">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    ghPath: Schema<string, string, "defined">;
+    defaultTimeoutMs: Schema<number, number, "volatile-defined">;
+    maxOutputChars: Schema<number, number, "volatile-defined">;
+    maxOutputBytes: Schema<number, number, "plain">;
+    cacheTtlMs: Schema<number, number, "defined">;
+    defaultListLimit: Schema<number, number, "volatile-defined">;
+    checkUpdate: Schema<boolean, boolean, "defined">;
+    updateCheckIntervalMs: Schema<number, number, "defined">;
+    registryUrl: Schema<string, string, "plain">;
+    agentEnvInjection: Schema<boolean, boolean, "defined">;
+    proxyUrl: Schema<string, string, "plain">;
+    toolsets: Schema<string[], string[], "plain">;
+    read_only: Schema<boolean, boolean, "plain">;
+}>>, "plain">;
+/** 校验并补齐默认值后的运行期配置（volatile 字段为稳定引用，非普通值）。 */
+export type Config = ReturnType<typeof ConfigSchema>;
+/** Cordis loader 消费的配置 Schema。 */
+export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
+    ghPath: Schema<string, string, "defined">;
+    defaultTimeoutMs: Schema<number, number, "volatile-defined">;
+    maxOutputChars: Schema<number, number, "volatile-defined">;
+    maxOutputBytes: Schema<number, number, "plain">;
+    cacheTtlMs: Schema<number, number, "defined">;
+    defaultListLimit: Schema<number, number, "volatile-defined">;
+    checkUpdate: Schema<boolean, boolean, "defined">;
+    updateCheckIntervalMs: Schema<number, number, "defined">;
+    registryUrl: Schema<string, string, "plain">;
+    agentEnvInjection: Schema<boolean, boolean, "defined">;
+    proxyUrl: Schema<string, string, "plain">;
+    toolsets: Schema<string[], string[], "plain">;
+    read_only: Schema<boolean, boolean, "plain">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    ghPath: Schema<string, string, "defined">;
+    defaultTimeoutMs: Schema<number, number, "volatile-defined">;
+    maxOutputChars: Schema<number, number, "volatile-defined">;
+    maxOutputBytes: Schema<number, number, "plain">;
+    cacheTtlMs: Schema<number, number, "defined">;
+    defaultListLimit: Schema<number, number, "volatile-defined">;
+    checkUpdate: Schema<boolean, boolean, "defined">;
+    updateCheckIntervalMs: Schema<number, number, "defined">;
+    registryUrl: Schema<string, string, "plain">;
+    agentEnvInjection: Schema<boolean, boolean, "defined">;
+    proxyUrl: Schema<string, string, "plain">;
+    toolsets: Schema<string[], string[], "plain">;
+    read_only: Schema<boolean, boolean, "plain">;
+}>>, "plain">;
+export declare function apply(ctx: Context, config?: Config): void;
 export type GitHubService = GhExecutor;
 export * from './types.js';
 export * from './version.js';

package/lib/main.js

@@ -1,3 +1,4 @@
+import Schema from '@deepseek-ai/schemastery';
 import { GhExecutor } from './executor.js';
 import { createPrTool } from './tools/pr.js';
 import { createIssueTool } from './tools/issue.js';
@@ -17,6 +18,7 @@ import { createDiscussionTool } from './tools/discussion.js';
 import { createProjectTool } from './tools/project.js';
 import { createCodespaceTool } from './tools/codespace.js';
 import { createHelpTool } from './tools/help.js';
+import { createTaskTool } from './tools/task.js';
 import { defaultTelemetryCollector } from './telemetry.js';
 import { registerGhCommand } from './commands/gh.js';
 import { registerApiRoutes } from './api/routes.js';
@@ -25,57 +27,121 @@ import { UpgradeManager } from './upgrade-manager.js';
 import { ProxyManager } from './proxy.js';
 import { NPM_PACKAGE_URL } from './version.js';
 import { loadUpdateSettings } from './update-settings.js';
+import { applyTier } from './tool-tiers.js';
 // 引用即生效：加载本模块以挂上 declare module '@deepseek-ai/cordis' 的 ctx.github 类型声明，
 // 并随下面 `export * from './github-service.js'` 一起传给消费方。
 import './github-service.js';
 export const name = 'dsh-github-flow';
 /**
- * 核心服务依赖声明
+ * 服务依赖声明：只声明唯一的硬依赖 `tools`。
  *
- * 必须显式声明 webServer 与 workspaceRegistry：
- * 在 Cordis 依赖隔离机制下，只有在 inject 显式声明的服务，当前插件作用域 ctx 才能持有
- * ctx.webServer 与 ctx.workspaceRegistry 引用，进而注册 Web UI 所需的后端 API 路由。
+ * 为什么其余三个服务降级为可选（`ctx.inject` 等待）：
+ * - `webServer` 由 `@deepseek-ai/dsh-web-app` 组合提供。`dsh-tui` 与纯 CLI profile 只装
+ *   `dsh-base`，没有这个服务——写成硬依赖会让插件在这些 profile 里**永久 PENDING**，
+ *   用户一个工具都拿不到（README 明确支持 CLI 安装）。
+ * - `commands` 由 `dsh-commands` 提供，同样不保证所有组合都有。
+ *
+ * cordis 的语义是：`inject` 里的服务缺席 ⇒ 插件不激活。因此"声明了就必须真存在"，
+ * 声明硬依赖却按可选写 `if (ctx.X)` 是最坏组合：既让可选服务变成了硬门槛，
+ * 又让降级分支永远走不到。
  */
-export const inject = ['tools', 'commands', 'webServer', 'workspaceRegistry'];
+export const inject = ['tools'];
 /**
- * 符合 Standard Schema / Cordis Loader 契约的 Config 运行时校验规范
+ * 本插件向宿主提供的服务名。
+ * cordis loader 读取该元数据（registry.d.ts），与 `ctx.provide('github', …)` 必须同名。
  */
-export const Config = {
-    '~standard': {
-        version: 1,
-        vendor: 'dsh',
-        validate(value) {
-            const cfg = (typeof value === 'object' && value !== null) ? value : {};
-            return {
-                value: {
-                    ghPath: typeof cfg.ghPath === 'string' ? cfg.ghPath : 'gh',
-                    defaultTimeoutMs: typeof cfg.defaultTimeoutMs === 'number' ? cfg.defaultTimeoutMs : 30_000,
-                    maxOutputChars: typeof cfg.maxOutputChars === 'number' ? cfg.maxOutputChars : 24_000,
-                    maxOutputBytes: typeof cfg.maxOutputBytes === 'number' ? cfg.maxOutputBytes : undefined,
-                    cacheTtlMs: typeof cfg.cacheTtlMs === 'number' ? cfg.cacheTtlMs : 15_000,
-                    defaultListLimit: typeof cfg.defaultListLimit === 'number' ? cfg.defaultListLimit : 20,
-                    checkUpdate: typeof cfg.checkUpdate === 'boolean' ? cfg.checkUpdate : true,
-                    agentEnvInjection: cfg.agentEnvInjection !== false,
-                    updateCheckIntervalMs: typeof cfg.updateCheckIntervalMs === 'number' ? cfg.updateCheckIntervalMs : 86_400_000,
-                    registryUrl: typeof cfg.registryUrl === 'string' ? cfg.registryUrl : undefined,
-                    proxyUrl: typeof cfg.proxyUrl === 'string' ? cfg.proxyUrl : undefined,
-                }
-            };
-        }
-    }
-};
-export function apply(ctx, config = {}) {
-    const executor = new GhExecutor(config);
+export const provide = 'github';
+/**
+ * 插件配置 Schema（Schemastery）。
+ *
+ * 与旧的手写 `'~standard'.validate()` 相比，这里拿到的是**真校验**：类型不符直接抛
+ * `ValidationError`（旧实现对脏配置静默回落到默认值，配错了永远不报错）。
+ * 未知键仍原样透传，与旧行为一致。
+ *
+ * `.volatile()` 的三个字段是「运行期可热改、不触发插件 reload」的稳定引用：
+ * 读取点必须走 `.get()`，否则拿到的是引用对象本身（详见 `resolvePluginConfig`）。
+ *
+ * 为什么 `checkUpdate` 刻意**不** volatile：`UpdateChecker.enabled` 是构造期只读字段，
+ * 它同时决定轮询定时器与启动横幅是否建立。标成 volatile 只会得到「配置改了、行为没变」
+ * 的假热更新；让它保持普通字段，改动时插件整体重载，语义才是对的。
+ */
+const ConfigSchema = Schema.object({
+    ghPath: Schema.string().default('gh'),
+    defaultTimeoutMs: Schema.number().default(30_000).volatile(),
+    maxOutputChars: Schema.number().default(24_000).volatile(),
+    // 不设默认值：缺省时由 maxOutputChars × 4 推导（executor 构造期），
+    // 显式给默认值会让「随 maxOutputChars 联动」这条语义失效。
+    maxOutputBytes: Schema.number(),
+    cacheTtlMs: Schema.number().default(15_000),
+    defaultListLimit: Schema.number().default(20).volatile(),
+    checkUpdate: Schema.boolean().default(true),
+    updateCheckIntervalMs: Schema.number().default(86_400_000),
+    registryUrl: Schema.string(),
+    agentEnvInjection: Schema.boolean().default(true),
+    proxyUrl: Schema.string(),
+    // 档位：缺省键直接缺席 → 下游按 full / 非只读处理，默认零破坏。
+    // 不设 default，是为了让「用户没配」与「用户显式配了 full」在诊断时仍可区分。
+    toolsets: Schema.array(Schema.string()),
+    read_only: Schema.boolean(),
+});
+/** Cordis loader 消费的配置 Schema。 */
+export const Config = ConfigSchema;
+/**
+ * 把 Schema 输出摊平为执行引擎消费的普通配置对象。
+ *
+ * 为什么必须显式摊平而不是 `{...config}`：volatile 字段是 `{ get(), [write]() }` 引用对象，
+ * 展开后仍是引用。`GhExecutor` 把它当数字用（`length > maxOutputChars`）不会报错，
+ * 只会让截断阈值变成 NaN 比较——静默失效，属于最难排查的一类回归。
+ * 逐字段列举而非遍历：新增配置项时这里会漏，但漏了 `tsc` 立刻报错，不会静默。
+ */
+function resolvePluginConfig(config) {
+    return {
+        ghPath: config.ghPath,
+        defaultTimeoutMs: config.defaultTimeoutMs.get(),
+        maxOutputChars: config.maxOutputChars.get(),
+        maxOutputBytes: config.maxOutputBytes,
+        cacheTtlMs: config.cacheTtlMs,
+        defaultListLimit: config.defaultListLimit.get(),
+        checkUpdate: config.checkUpdate,
+        updateCheckIntervalMs: config.updateCheckIntervalMs,
+        // 可选字符串字段在 Schema 里没有 default，缺省时键直接缺席，显式 null 也会被放行；
+        // 统一归一成 undefined，下游 `if (x)` 语义才不会被 null 误伤。
+        registryUrl: config.registryUrl ?? undefined,
+        agentEnvInjection: config.agentEnvInjection,
+        proxyUrl: config.proxyUrl ?? undefined,
+        toolsets: config.toolsets,
+        read_only: config.read_only,
+    };
+}
+/**
+ * 监听宿主事件。
+ *
+ * 为什么要这层收窄：`ctx.on` 的类型参数是 `keyof Events`，而本插件依赖的两个事件
+ * 声明都在本仓之外——`tools/result` 来自 `@deepseek-ai/dsh-tools`，
+ * `loader/volatile-update` 来自 `@deepseek-ai/cordis-plugin-loader`。
+ * 本仓不能直接依赖前者：它的 peer 闭包引用了未发布的 `@deepseek-ai/dsh-type-meta`
+ * （npm 404），`pnpm install` 直接失败。
+ *
+ * 为什么不用 `declare module '@deepseek-ai/cordis'` 自行合并 `Events`：消费方若同时加载
+ * dsh-tools，两份方法签名会合成重载，而本仓这份 `any` 签名会把对方的精确类型盖掉。
+ * 只在本文件内收窄，不污染全局契约。
+ */
+function onHostEvent(ctx, name, listener) {
+    ctx.on(name, listener);
+}
+export function apply(ctx, config = Config({})) {
+    const plain = resolvePluginConfig(config);
+    const executor = new GhExecutor(plain);
     // 代理管理器：优先读取用户在驾驶舱保存的 proxy.json，回落 cordis.patch.yml 的
     // proxyUrl 预置值；两者皆无时保持直连（gh 自然继承宿主系统环境变量）。
     // 装配后 executor/upgradeManager/updater 三条外联链路全部经它路由。
-    const proxyManager = new ProxyManager(config.proxyUrl);
+    const proxyManager = new ProxyManager(plain.proxyUrl);
     executor.attachProxyManager(proxyManager);
     const updateChecker = new UpdateChecker({
-        intervalMs: config.updateCheckIntervalMs,
-        customRegistry: config.registryUrl,
+        intervalMs: plain.updateCheckIntervalMs,
+        customRegistry: plain.registryUrl,
         // checkUpdate: false 熔断全部探测入口（路由/命令/启动横幅共用此实例）
-        enabled: config.checkUpdate !== false,
+        enabled: plain.checkUpdate,
     });
     // 更新源设置（UI 持久化 store 优先于 Cordis 静态配置）：
     // 启动时读取并应用到 checker；UI 保存时经路由直接调 applySettings 热切换。
@@ -87,65 +153,96 @@ export function apply(ctx, config = {}) {
     // 注入查询函数而非静态值：用户切源后，下一次一键升级的 registry 实时跟随
     upgradeManager.attachUpdateModeQuery(() => updateChecker.getSourceMode());
     // 1. 兑现生态服务契约：将 GitHub 执行引擎作为服务暴露给其他 DSH 插件 (ctx.github)
-    if (ctx.provide && typeof ctx.provide === 'function') {
-        ctx.provide('github', executor);
-    }
-    else {
-        ctx.github = executor;
-    }
+    // 服务注册由当前 fiber 拥有：返回的 disposer 或 fiber 卸载时自动注销（cordis reflect.d.ts:29-43），
+    // 因此不需要 `ctx.github = executor` 这类裸赋值兜底——它绕过 inject 语义且永不清理。
+    ctx.provide('github', executor);
     // 2. 注册 Cordis tools/result 事件切面（无侵入全量工具审计与降级率打点）
-    if (ctx.on && typeof ctx.on === 'function') {
-        ctx.on('tools/result', (exec, result) => {
-            try {
-                const toolName = exec?.name || exec?.tool?.name || '';
-                if (typeof toolName === 'string' && toolName.startsWith('github_')) {
-                    const args = exec?.arguments || exec?.args || {};
-                    defaultTelemetryCollector.recordCall(toolName, args, result);
-                }
-            }
-            catch {
-                // Fail-Open 非阻塞防线：严禁打点逻辑异常影响主工具调用
+    onHostEvent(ctx, 'tools/result', (exec, result) => {
+        try {
+            const toolName = exec?.name || exec?.tool?.name || '';
+            if (typeof toolName === 'string' && toolName.startsWith('github_')) {
+                const args = exec?.arguments || exec?.args || {};
+                defaultTelemetryCollector.recordCall(toolName, args, result);
             }
-        });
-    }
+        }
+        catch {
+            // Fail-Open 非阻塞防线：严禁打点逻辑异常影响主工具调用
+        }
+    });
     // 3. 注册人类 Slash 命令 (/gh status, /gh upgrade, /gh help)
-    if (ctx.commands) {
-        registerGhCommand(ctx.commands, executor, updateChecker, defaultTelemetryCollector);
-    }
+    // 用 ctx.inject 声明式等待，而不是一次性 ctx.get 探测：服务若晚于本插件就绪，
+    // 一次性探测拿到的是 undefined，且**永远没有第二次机会**，/gh 就此消失。
+    // ctx.inject 的嵌套 fiber 在服务出现时补触发；服务始终不出现则它自己保持 PENDING，
+    // 外层插件照常 ACTIVE（18 个工具不受影响）。这就是「可选依赖」在 cordis 里的正确写法。
+    ctx.inject(['commands'], (c) => {
+        registerGhCommand(c.get('commands'), executor, updateChecker, defaultTelemetryCollector);
+    });
     // 4. 注册 Agent 模型工具集（核心领域工具 + 元指南）
-    if (ctx.tools) {
-        ctx.tools.register(createPrTool(executor));
-        ctx.tools.register(createIssueTool(executor));
-        ctx.tools.register(createRunTool(executor));
-        ctx.tools.register(createRepoTool(executor));
-        ctx.tools.register(createApiTool(executor));
-        ctx.tools.register(createReleaseTool(executor));
-        ctx.tools.register(createSecretTool(executor));
-        ctx.tools.register(createSkillTool(executor));
-        ctx.tools.register(createLabelTool(executor));
-        ctx.tools.register(createRulesetTool(executor));
-        ctx.tools.register(createCacheTool(executor));
-        ctx.tools.register(createGistTool(executor));
-        ctx.tools.register(createStatusTool(executor, defaultTelemetryCollector));
-        ctx.tools.register(createAgentTaskTool(executor));
-        ctx.tools.register(createDiscussionTool(executor));
-        ctx.tools.register(createProjectTool(executor));
-        ctx.tools.register(createCodespaceTool(executor));
-        ctx.tools.register(createHelpTool(executor));
-    }
-    // 4. 注册面向 Client 端的 WebServer HTTP 路由（如果当前环境启用了 Web UI 服务）
-    if (ctx.webServer) {
-        // 传入 ctx 作用域对象，使 routes 能够通过 ctx.effect 绑定生命周期并在插件卸载/重载时自动注销；
-        // cacheTtlMs 传给路由层以尊重用户的缓存 TTL 配置。
-        // proxyManager 传入以挂载 /api/github/proxy* 设置路由（驾驶舱代理设置入口）。
-        registerApiRoutes(ctx, executor, ctx.workspaceRegistry, config.cacheTtlMs || 15_000, updateChecker, upgradeManager, proxyManager);
+    // `tools` 在 inject 内，运行期必然存在；其权威类型声明在 @deepseek-ai/dsh-tools，
+    // 本仓不重复 declare module（会与消费方的同一份声明冲突），故在此局部收窄。
+    const tools = ctx.tools;
+    // 先建全量数组再统一过档位与闸门：过滤点唯一，且 applyTier / wrapWithGate 都是纯函数，
+    // 可以完全离线单测（见 test/phase37-toolset / phase38-gate）。
+    const allTools = [
+        createPrTool(executor),
+        createIssueTool(executor),
+        createRunTool(executor),
+        createRepoTool(executor),
+        createApiTool(executor),
+        createReleaseTool(executor),
+        createSecretTool(executor),
+        createSkillTool(executor),
+        createLabelTool(executor),
+        createRulesetTool(executor),
+        createCacheTool(executor),
+        createGistTool(executor),
+        createStatusTool(executor, defaultTelemetryCollector),
+        createAgentTaskTool(executor),
+        createDiscussionTool(executor),
+        createProjectTool(executor),
+        createCodespaceTool(executor),
+        createHelpTool(executor),
+        // 任务级原语（s8）：与 18 个领域工具并存，档位里用 core 预设二选一
+        createTaskTool(executor),
+    ];
+    const tier = applyTier(allTools, { toolsets: plain.toolsets, read_only: plain.read_only });
+    if (tier.dropped.length > 0) {
+        // 不静默：档位/只读模式剪掉的工具要能从日志里看到，否则"模型看不见某工具"无法排查
+        console.log(`[dsh-github-flow] 按档位配置未注册 ${tier.dropped.length} 个工具：${tier.dropped.join(', ')}`);
     }
-    // 5. 启动后低优先级后台闲时静默探测：若有新版本，仅输出一次友好的控制台提示
-    if (config.checkUpdate !== false) {
+    // 闸门已在各工具工厂内部经 wrapWithGate 生效，这里只做档位过滤后的注册。
+    for (const tool of tier.kept)
+        tools.register(tool);
+    // 5. 注册面向 Client 端的 WebServer HTTP 路由
+    // 同样用 ctx.inject 等待 webServer（理由同第 3 步）。
+    // 关键：绝不能在外层 `ctx.get('webServer')` 之后又让 routes 内部去读 `ctx.webServer`——
+    // 未 inject 时那个属性读会抛 `cannot get property "webServer" without inject`，
+    // 让 CLI/TUI profile 从「PENDING」变成「加载失败」。
+    // 这里把 webServer 显式作为末位参数传下去，routes 内部不再做属性读回退。
+    ctx.inject(['webServer'], (c) => {
+        registerApiRoutes(c, executor, plain.cacheTtlMs || 15_000, updateChecker, upgradeManager, proxyManager, c.get('webServer'));
+    });
+    // 6. volatile 字段热更新：loader 把新值提交进运行中的 fiber（不 reload），
+    // 这里把它推给执行引擎。事件由 @deepseek-ai/cordis-plugin-loader 派发，
+    // 只在「该字段确实声明了 .volatile()」时触发。
+    // 只推 GhExecutor.updateConfig 真正认的字段：认了不改的字段等于假热更新。
+    onHostEvent(ctx, 'loader/volatile-update', () => {
+        executor.updateConfig({
+            defaultTimeoutMs: config.defaultTimeoutMs.get(),
+            maxOutputChars: config.maxOutputChars.get(),
+            defaultListLimit: config.defaultListLimit.get(),
+            // maxOutputBytes 不是 volatile（它不该被单独热改），但**必须一起推**：
+            // updateConfig 收到 maxOutputChars 就会把 maxOutputBytes 重算成 ×4
+            // （executor.ts:218-222）。不带上用户显式配置的硬上限，一次热更新就会把它冲掉
+            // ——实测 {maxOutputChars:1000, maxOutputBytes:500} 会变成 4000。
+            maxOutputBytes: config.maxOutputBytes,
+        });
+    });
+    // 7. 启动后低优先级后台闲时静默探测：若有新版本，仅输出一次友好的控制台提示
+    if (plain.checkUpdate) {
         // 包裹在 ctx.effect 中（Cordis 规范）：热重载/卸载发生在 3 秒延迟窗口内时，
         // 取消挂起的定时器，避免旧实例在新实例加载后仍向控制台打印升级横幅。
-        // 无头/测试环境缺 ctx.effect 时优雅退化为裸定时器（一次性触发，无泄漏）。
-        const scheduleProbe = () => {
+        ctx.effect(() => {
             const timer = setTimeout(() => {
                 updateChecker.check(false).then((info) => {
                     if (info.hasUpdate) {
@@ -160,13 +257,7 @@ export function apply(ctx, config = {}) {
                 }).catch(() => { });
             }, 3_000);
             return () => clearTimeout(timer);
-        };
-        if (typeof ctx.effect === 'function') {
-            ctx.effect(scheduleProbe);
-        }
-        else {
-            scheduleProbe();
-        }
+        });
     }
 }
 export * from './types.js';

package/lib/renderers/common.d.ts

@@ -1,6 +1,3 @@
-/**
- * DSH GitHub Flow - 通用 Markdown 格式化原子工具与状态徽章
- */
 /** 安全清洗表格单元格文本：转义竖线，压缩换行，限制最大长度 */
 export declare function sanitizeCell(text: any, maxLen?: number): string;
 /** 格式化 PR / Issue 状态药丸徽章 */

package/lib/renderers/common.js

@@ -1,6 +1,10 @@
 /**
  * DSH GitHub Flow - 通用 Markdown 格式化原子工具与状态徽章
+ *
+ * 状态徽章的实现已下沉到 `src/shared/state-badges.ts`（与客户端 UI 共用同一份映射）。
+ * 这里保留 `format*Badge` 的函数名与签名，服务端 14 处调用点零改动。
  */
+import { badgeText, prStateBadge, ciBadge, conflictBadge, releaseBadge, } from '../shared/state-badges.js';
 /** 安全清洗表格单元格文本：转义竖线，压缩换行，限制最大长度 */
 export function sanitizeCell(text, maxLen = 80) {
     if (text === null || text === undefined || text === '')
@@ -16,18 +20,7 @@ export function sanitizeCell(text, maxLen = 80) {
 }
 /** 格式化 PR / Issue 状态药丸徽章 */
 export function formatStateBadge(state, isDraft) {
-    if (!state)
-        return '-';
-    const s = state.toUpperCase();
-    if (isDraft)
-        return '⚪ DRAFT';
-    if (s === 'OPEN')
-        return '🟢 OPEN';
-    if (s === 'MERGED')
-        return '🟣 MERGED';
-    if (s === 'CLOSED')
-        return '🔴 CLOSED';
-    return s;
+    return badgeText(prStateBadge(state, isDraft));
 }
 /**
  * 格式化 CI 工作流状态徽章。
@@ -36,44 +29,15 @@ export function formatStateBadge(state, isDraft) {
  * 同一组徽章；state 参数兜底（in_progress/queued 等进行中态）。
  */
 export function formatCiBadge(status, conclusion) {
-    const conc = (conclusion || '').toLowerCase();
-    const st = (status || '').toLowerCase();
-    if (conc === 'success' || conc === 'pass')
-        return '✅ ' + conc;
-    if (conc === 'failure' || conc === 'fail')
-        return '❌ ' + conc;
-    if (conc === 'cancelled' || conc === 'cancel')
-        return '🚫 ' + conc;
-    if (conc === 'skipped' || conc === 'skipping')
-        return '⏭️ ' + conc;
-    if (conc === 'pending')
-        return '⏳ pending';
-    if (st === 'in_progress')
-        return '⏳ running';
-    if (st === 'queued')
-        return '⏱️ queued';
-    return conc || st || '-';
+    return badgeText(ciBadge(status, conclusion));
 }
 /** 格式化合并冲突状态 */
 export function formatConflictBadge(status) {
-    if (!status)
-        return '-';
-    const s = status.toUpperCase();
-    if (s === 'CLEAN')
-        return '✅ CLEAN';
-    if (s === 'DIRTY' || s === 'CONFLICT')
-        return '⚠️ CONFLICT';
-    if (s === 'BLOCKED')
-        return '⛔ BLOCKED';
-    return s;
+    return badgeText(conflictBadge(status));
 }
 /** 格式化 Release 状态徽章 */
 export function formatReleaseBadge(isDraft, isPrerelease) {
-    if (isDraft)
-        return '⚪ DRAFT';
-    if (isPrerelease)
-        return '🍼 PRE';
-    return '✅ STABLE';
+    return badgeText(releaseBadge(isDraft, isPrerelease));
 }
 /**
  * 降级链路可见标注（runGuarded 契约的渲染兑现）。

package/lib/renderers/markdown.d.ts

@@ -20,3 +20,4 @@ export * from './agent-task.js';
 export * from './discussion.js';
 export * from './project.js';
 export * from './codespace.js';
+export * from './task.js';

package/lib/renderers/markdown.js

@@ -20,3 +20,4 @@ export * from './agent-task.js';
 export * from './discussion.js';
 export * from './project.js';
 export * from './codespace.js';
+export * from './task.js';

package/lib/renderers/pr.js

@@ -1,4 +1,5 @@
 import { sanitizeCell, formatStateBadge, formatCiBadge, formatConflictBadge } from './common.js';
+import { renderReviewRules } from '../review-rules.js';
 /**
  * PR 领域渲染器：负责 PR 列表高密度表格、CI Checks、分支状态与单卡详情格式化
  */
@@ -89,17 +90,41 @@ export function renderPrMarkdown(args, value) {
         const link = value.url ? `[#${value.number}](${value.url})` : `#${value.number}`;
         const badge = formatStateBadge(value.state, value.isDraft);
         const author = value.author?.login ? `@${value.author.login}` : '-';
+        /*
+         * 分支名会移动（force-push / 新提交），拿它当审查锚点等于「我审的到底是哪一版」
+         * 永远说不清。`branch@a1b2c3d` 是 git 世界的通用写法：7 位足够人读，
+         * 完整 SHA 仍在 JSON 里（headRefOid），需要精确引用时取它。
+         * 老服务端 / 老 gh 没有 headRefOid 时只显示分支名，绝不渲染 `@undefined`。
+         */
+        const headSha = typeof value.headRefOid === 'string' && value.headRefOid.length >= 7
+            ? `@${value.headRefOid.slice(0, 7)}`
+            : '';
         const lines = [
             `### ${badge} ${value.title} (${link})`,
-            `- **作者**: ${author} | **分支**: \`${value.headRefName || '-'}\` → \`${value.baseRefName || 'main'}\``,
+            `- **作者**: ${author} | **分支**: \`${value.headRefName || '-'}${headSha}\` → \`${value.baseRefName || 'main'}\``,
             `- **合并判定**: ${formatConflictBadge(value.mergeable || value.mergeStateStatus)} | **审查判定**: ${value.reviewDecision || 'NONE'}`,
         ];
         if (Array.isArray(value.labels) && value.labels.length > 0) {
             lines.push(`- **标签**: ${value.labels.map((l) => `\`${l.name || l}\``).join(' ')}`);
         }
+        // 清单截断必须让 Agent 也知道（人看 UI、Agent 看这里，同一事实两处都要说）
+        if (typeof value.changedFiles === 'number' && Array.isArray(value.files) && value.files.length < value.changedFiles) {
+            lines.push(`- **变动文件**: 仅列出前 ${value.files.length} / ${value.changedFiles} 个（gh 单次最多返回 100 条）`);
+        }
         if (value.body) {
             lines.push('\n**正文说明:**\n```markdown\n' + sanitizeCell(value.body, 300) + '\n```');
         }
+        /*
+         * 仓库审查规则（AGENTS.md）：人看 UI、Agent 看这里，同一事实两处都要说。
+         * 只有工具确实注入时才渲染（`reviewRules` 键不存在 = 工作区没有规则文件，
+         * 此时不得输出一个空章节让人以为「规则为空」）。
+         *
+         * 渲染逻辑复用 `review-rules.ts` 的 `renderReviewRules`——同一条规则只能有
+         * 一处实现，否则「工具返回的 JSON」与「Markdown 输出」迟早会漂移。
+         */
+        const rulesMd = renderReviewRules(value.reviewRules);
+        if (rulesMd)
+            lines.push(rulesMd);
         return lines.join('\n');
     }
     // 兜底降级

package/lib/renderers/task.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `github_task` 的 Markdown 渲染器。
+ *
+ * 为什么单独渲染而不是 JSON 直出：原语的返回值是「给模型看的结论包」，
+ * 其中 `cost` 与 `truncated` 是审计信息、`facts` 是结构化事实。
+ * 直接 JSON.stringify 会把最重要的 `summary` 埋在括号里；
+ * 而只渲染 summary 又会丢掉「这次花了多少」——两者都要，但要有主次。
+ */
+export declare function renderTaskMarkdown(args: any, value: any): string;