@roll-agent/core 0.15.0 → 0.16.0

package/dist/cli/chat/ink/live-region.js

@@ -1 +1 @@
-import{createElement as n}from"react";import{Box as l,Text as t}from"ink";import{Spinner as e}from"./spinner.js";import{ThinkingText as i}from"./thinking-text.js";import{ToolLabel as o}from"./tool-label.js";export function LiveRegion({live:r}){return n(l,{flexDirection:"column"},r.streamingText.length>0?n(l,{marginTop:1},n(i,{text:r.thinkTagOpen?`<think>${r.streamingText}`:r.streamingText})):null,r.thinking?n(l,{marginTop:1},n(e,null),n(t,{dimColor:!0}," 思考中…")):null,...r.activeTools.map(i=>n(l,{key:i.toolCallId,marginLeft:2},n(e,null),n(t,null," "),n(o,{name:i.name}),i.args.length>0?n(t,{dimColor:!0},` ${i.args}`):null)),r.compacting?n(l,null,n(e,null),n(t,{dimColor:!0}," 压缩上下文中…")):null)}
+import{createElement as l}from"react";import{Box as n,Text as t}from"ink";import{Spinner as i}from"./spinner.js";import{ThinkingText as o}from"./thinking-text.js";import{ToolLabel as e}from"./tool-label.js";const r=3;function m(l){return void 0===l?[]:l.split("\n").map(l=>l.trimEnd()).filter(l=>l.length>0).slice(-3)}export function LiveRegion({live:r}){return l(n,{flexDirection:"column"},r.streamingText.length>0?l(n,{marginTop:1},l(o,{text:r.thinkTagOpen?`<think>${r.streamingText}`:r.streamingText})):null,r.thinking?l(n,{marginTop:1},l(i,null),l(t,{dimColor:!0}," 思考中…")):null,...r.activeTools.map(o=>l(n,{key:o.toolCallId,marginLeft:2,flexDirection:"column"},l(n,null,l(i,null),l(t,null," "),l(e,{name:o.name}),o.args.length>0?l(t,{dimColor:!0},` ${o.args}`):null),...m(o.outputTail).map((n,i)=>l(t,{key:`${o.toolCallId}-tail-${String(i)}`,dimColor:!0},`    ${n}`)))),r.compacting?l(n,null,l(i,null),l(t,{dimColor:!0}," 压缩上下文中…")):null)}

package/dist/cli/chat/ink/state.d.ts

@@ -5,6 +5,7 @@ export interface ToolRowState {
     readonly toolCallId: string;
     readonly name: string;
     readonly args: string;
+    readonly outputTail?: string;
 }
 export type HistoryItem = {
     readonly kind: "banner";

package/dist/cli/chat/ink/state.js

@@ -1 +1 @@
-import{formatToolInput as t}from"../../utils/tool-format.js";import{GLYPHS as e}from"../../utils/glyphs.js";import{endsInsideThink as i}from"./thinking-text.js";const n={streamingText:"",thinking:!1,thinkTagOpen:!1,activeTools:[],compacting:!1,producedOutput:!1};function o(t,e){return e?`<think>${t}`:t}export function createInitialState(t,e,i){return{history:i?.history??[],draft:"",live:n,status:{model:t,contextWindow:e,turnUsage:void 0,sessionUsage:void 0,contextInputTokens:void 0,outputTokensPerSecond:void 0,thinkingLevel:i?.thinkingLevel??"medium",autoApprove:!1},phase:"idle",pendingConfirm:void 0}}export function buildConfirmPrompt(t){const e=t.reason?`（${t.reason}）`:"";return`执行 ${t.agentName}.${t.toolName}${e}?`}function r(t){const i="auto"===t.reason?"自动压缩":"手动压缩",n=t.truncatedTools?`，精简 ${String(t.truncatedTools)} 个工具结果`:"";return 0!==t.removed||t.truncatedTools?`${e.compact} ${i}(${t.strategy})：移除 ${String(t.removed)} 条 → 保留 ${String(t.kept)} 条${n}`:`${e.compact} ${i}：无需压缩`}const s=[["已取消执行","已取消"],["策略拒绝执行","策略拒绝"]];function a(t){return"string"==typeof t?t:"object"==typeof t&&null!==t&&"output"in t&&"string"==typeof t.output?t.output:void 0}export function denialLabel(t){const e=a(t);if(void 0!==e)return s.find(([t])=>e.startsWith(t))?.[1]}function u(t,e,i){const n=t.live.activeTools.find(t=>t.toolCallId===i.toolCallId),o=n?.name??`${i.agentName}.${i.toolName}`,r=n?.args??"",s=i.isError?denialLabel(i.output):void 0,a=void 0!==s?{kind:"denied",id:e,name:o,label:s}:{kind:"tool",id:e,name:o,args:r,ok:!i.isError};return{...t,history:[...t.history,a],live:{...t.live,activeTools:t.live.activeTools.filter(t=>t.toolCallId!==i.toolCallId)}}}function l(e,s,a){switch(a.type){case"message-start":return{...e,live:{...e.live,thinking:!0}};case"text-delta":return{...e,live:{...e.live,thinking:!1,producedOutput:!0,streamingText:e.live.streamingText+a.delta}};case"tool-call":{const n=e.live.streamingText.length>0?[{kind:"assistant",id:s,text:o(e.live.streamingText,e.live.thinkTagOpen)}]:[];return{...e,history:[...e.history,...n],live:{...e.live,thinking:!1,producedOutput:!0,streamingText:"",thinkTagOpen:i(e.live.streamingText,e.live.thinkTagOpen),activeTools:[...e.live.activeTools,{toolCallId:a.toolCallId,name:`${a.agentName}.${a.toolName}`,args:t(a.input)}]}}}case"tool-result":return u(e,s,a);case"confirmation-required":return{...e,phase:"confirm",pendingConfirm:{approvalId:a.approvalId,prompt:buildConfirmPrompt(a),args:t(a.input)}};case"compaction-start":return{...e,live:{...e.live,compacting:!0}};case"context-compacted":return{...e,live:{...e.live,compacting:!1},history:[...e.history,{kind:"compaction",id:s,notice:r(a)}]};case"message-finish":{const t=[];return e.live.streamingText.length>0?t.push({kind:"assistant",id:s,text:o(e.live.streamingText,e.live.thinkTagOpen)}):!e.live.producedOutput&&(a.totalUsage?.outputTokens??0)>0&&t.push({kind:"notice",id:s,text:"模型本轮只返回了 thinking/reasoning，没有生成可见回复"}),a.stoppedAtStepLimit&&t.push({kind:"notice",id:`${s}-step-limit`,text:"已达单轮最大工具步数，任务可能未完成 — 继续追问即可接着做，或调高 runtime.max-steps"}),{...e,history:[...e.history,...t],live:{...n},status:{...e.status,turnUsage:a.totalUsage,sessionUsage:a.sessionUsage,contextInputTokens:a.contextInputTokens,outputTokensPerSecond:a.outputTokensPerSecond}}}case"error":return{...e,history:[...e.history,{kind:"error",id:s,message:a.message}],live:{...n}};default:return e}}export function chatReducer(t,e){switch(e.type){case"submit-user":return{...t,history:[...t.history,{kind:"user",id:e.id,text:e.text}],draft:"",live:{...n},phase:"busy",pendingConfirm:void 0};case"set-draft":return{...t,draft:e.value};case"set-thinking":return{...t,status:{...t.status,thinkingLevel:e.level}};case"set-auto":return{...t,status:{...t.status,autoApprove:e.value}};case"commit-history":return{...t,history:[...t.history,e.item],draft:""};case"start-compaction":return{...t,live:{...n},phase:"busy",pendingConfirm:void 0};case"session-event":return l(t,e.id,e.event);case"confirm-resolved":return{...t,phase:"busy",pendingConfirm:void 0};case"turn-end":return{...t,phase:"idle",live:{...n}};default:return t}}
+import{formatToolInput as t,formatApprovalDetails as e}from"../../utils/tool-format.js";import{GLYPHS as i}from"../../utils/glyphs.js";import{endsInsideThink as o}from"./thinking-text.js";const n=2e3,r={streamingText:"",thinking:!1,thinkTagOpen:!1,activeTools:[],compacting:!1,producedOutput:!1};function s(t,e){return e?`<think>${t}`:t}export function createInitialState(t,e,i){return{history:i?.history??[],draft:"",live:r,status:{model:t,contextWindow:e,turnUsage:void 0,sessionUsage:void 0,contextInputTokens:void 0,outputTokensPerSecond:void 0,thinkingLevel:i?.thinkingLevel??"medium",autoApprove:!1},phase:"idle",pendingConfirm:void 0}}export function buildConfirmPrompt(t){const e=t.reason?`（${t.reason}）`:"";return`执行 ${t.agentName}.${t.toolName}${e}?`}function a(t){const e="auto"===t.reason?"自动压缩":"手动压缩",o=t.truncatedTools?`，精简 ${String(t.truncatedTools)} 个工具结果`:"";return 0!==t.removed||t.truncatedTools?`${i.compact} ${e}(${t.strategy})：移除 ${String(t.removed)} 条 → 保留 ${String(t.kept)} 条${o}`:`${i.compact} ${e}：无需压缩`}const l=[["已取消执行","已取消"],["策略拒绝执行","策略拒绝"]];function u(t){return"string"==typeof t?t:"object"==typeof t&&null!==t&&"output"in t&&"string"==typeof t.output?t.output:void 0}export function denialLabel(t){const e=u(t);if(void 0!==e)return l.find(([t])=>e.startsWith(t))?.[1]}function c(t,e,i){const o=t.live.activeTools.find(t=>t.toolCallId===i.toolCallId),n=o?.name??`${i.agentName}.${i.toolName}`,r=o?.args??"",s=i.isError?denialLabel(i.output):void 0,a=void 0!==s?{kind:"denied",id:e,name:n,label:s}:{kind:"tool",id:e,name:n,args:r,ok:!i.isError};return{...t,history:[...t.history,a],live:{...t.live,activeTools:t.live.activeTools.filter(t=>t.toolCallId!==i.toolCallId)}}}function d(i,l,u){switch(u.type){case"message-start":return{...i,live:{...i.live,thinking:!0}};case"text-delta":return{...i,live:{...i.live,thinking:!1,producedOutput:!0,streamingText:i.live.streamingText+u.delta}};case"tool-call":{const e=i.live.streamingText.length>0?[{kind:"assistant",id:l,text:s(i.live.streamingText,i.live.thinkTagOpen)}]:[];return{...i,history:[...i.history,...e],live:{...i.live,thinking:!1,producedOutput:!0,streamingText:"",thinkTagOpen:o(i.live.streamingText,i.live.thinkTagOpen),activeTools:[...i.live.activeTools,{toolCallId:u.toolCallId,name:`${u.agentName}.${u.toolName}`,args:t(u.input)}]}}}case"tool-output-delta":{const t=i.live.activeTools.map(t=>{if(t.toolCallId!==u.toolCallId)return t;const e=`${t.outputTail??""}${u.delta}`,i=e.length>n?e.slice(e.length-n):e;return{...t,outputTail:i}});return{...i,live:{...i.live,activeTools:t}}}case"tool-result":return c(i,l,u);case"confirmation-required":return{...i,phase:"confirm",pendingConfirm:{approvalId:u.approvalId,prompt:buildConfirmPrompt(u),args:e(u.input)}};case"compaction-start":return{...i,live:{...i.live,compacting:!0}};case"context-compacted":return{...i,live:{...i.live,compacting:!1},history:[...i.history,{kind:"compaction",id:l,notice:a(u)}]};case"message-finish":{const t=[];return i.live.streamingText.length>0?t.push({kind:"assistant",id:l,text:s(i.live.streamingText,i.live.thinkTagOpen)}):!i.live.producedOutput&&(u.totalUsage?.outputTokens??0)>0&&t.push({kind:"notice",id:l,text:"模型本轮只返回了 thinking/reasoning，没有生成可见回复"}),u.stoppedAtStepLimit&&t.push({kind:"notice",id:`${l}-step-limit`,text:"已达单轮最大工具步数，任务可能未完成 — 继续追问即可接着做，或调高 runtime.max-steps"}),{...i,history:[...i.history,...t],live:{...r},status:{...i.status,turnUsage:u.totalUsage,sessionUsage:u.sessionUsage,contextInputTokens:u.contextInputTokens,outputTokensPerSecond:u.outputTokensPerSecond}}}case"error":return{...i,history:[...i.history,{kind:"error",id:l,message:u.message}],live:{...r}};default:return i}}export function chatReducer(t,e){switch(e.type){case"submit-user":return{...t,history:[...t.history,{kind:"user",id:e.id,text:e.text}],draft:"",live:{...r},phase:"busy",pendingConfirm:void 0};case"set-draft":return{...t,draft:e.value};case"set-thinking":return{...t,status:{...t.status,thinkingLevel:e.level}};case"set-auto":return{...t,status:{...t.status,autoApprove:e.value}};case"commit-history":return{...t,history:[...t.history,e.item],draft:""};case"start-compaction":return{...t,live:{...r},phase:"busy",pendingConfirm:void 0};case"session-event":return d(t,e.id,e.event);case"confirm-resolved":return{...t,phase:"busy",pendingConfirm:void 0};case"turn-end":return{...t,phase:"idle",live:{...r}};default:return t}}

package/dist/cli/commands/agent-add.js

@@ -1 +1 @@
-import{defineCommand as e}from"citty";import{resolve as t}from"node:path";import{existsSync as r,mkdirSync as i}from"node:fs";import{execFile as o}from"node:child_process";import{promisify as n}from"node:util";import{inspectAgentEnvRequirements as s}from"../../config/helpers.js";import{loadAgentsConfig as a}from"../../config/loader.js";import{discoverAgent as p}from"../../registry/discovery.js";import{writeRemoteSkillManifest as c}from"../../registry/manifest.js";import{AgentStore as d}from"../../registry/store.js";import{log as l}from"../utils/output.js";import{createInstallCommand as m,detectInstallCommand as g,formatPackageManagerCommand as f,formatPackageManagerError as u,runPackageManager as h}from"../utils/package-manager.js";const y=n(o);function $(e){return e.startsWith("https://")||e.startsWith("http://")||e.startsWith("git@")||e.endsWith(".git")}function v(e){return(e.split("/").pop()??e).replace(/\.git$/,"")}export default e({meta:{description:"注册本地目录、Git 仓库或远程 MCP endpoint"},args:{path:{type:"positional",description:"本地 Agent 目录或 Git 仓库 URL；远程 endpoint 请用 --remote",required:!1},remote:{type:"string",description:"远程 MCP endpoint；需要同时提供 --name 和 --description"},name:{type:"string",description:"远程 Agent 名称（仅 --remote 时使用）"},description:{type:"string",description:"远程 Agent 描述（仅 --remote 时使用）"}},async run({args:e}){const{agentsConfig:o}=a();let n;if(e.remote){if(!e.name||!e.description)return l.error("远程注册需要同时提供 --name 和 --description"),void(process.exitCode=1);n=c({dataDir:o.dataDir,name:e.name,description:e.description,endpoint:e.remote})}else{if(!e.path)return l.error("请提供本地路径、Git URL，或使用 --remote <endpoint> 注册远程 Agent"),void(process.exitCode=1);if($(e.path)){const s=v(e.path),a=t(o.dataDir,"repos",s);if(r(a)){l.info(`仓库目录已存在，拉取最新代码: ${a}`);try{await y("git",["pull"],{cwd:a})}catch(e){return l.error(`git pull 失败: ${e instanceof Error?e.message:String(e)}`),void(process.exitCode=1)}}else{l.info(`克隆 ${e.path}...`);const n=t(o.dataDir,"repos");r(n)||i(n,{recursive:!0});try{await y("git",["clone",e.path,a]),l.success("克隆完成")}catch(e){return l.error(`git clone 失败: ${e instanceof Error?e.message:String(e)}`),void(process.exitCode=1)}}n=a}else if(n=t(e.path),!r(n))return l.error(`路径不存在: ${n}`),void(process.exitCode=1)}l.info("解析 SKILL.md...");const s=p(n);l.debug(`名称: ${s.skill.name}`),l.debug(`描述: ${s.skill.description}`),l.debug(`传输: ${s.transport.type}`);const L=t(n,"package.json"),A="1"===process.env.ROLL_SKIP_INSTALL;if(e.remote)l.info("远程 Agent 使用本地 manifest，无需安装依赖。");else if(r(L)&&!A){const e=g(n)??m("pnpm");l.info(`安装依赖 (${f(e)})...`);try{await h(e,{cwd:n}),l.success("依赖安装完成")}catch(t){return l.error(`依赖安装失败: ${u(e,t)}`),void(process.exitCode=1)}}else r(L)&&A&&l.warn("检测到 ROLL_SKIP_INSTALL=1，跳过依赖安装。");const j=e.remote?{type:"remote-manifest",endpoint:e.remote}:e.path&&$(e.path)?{type:"git",url:e.path}:{type:"local-path",path:n},w=new d(o.dataDir),C={skill:s.skill,transport:s.transport,runtime:s.runtime,installPath:n,registeredAt:(new Date).toISOString(),status:"idle",source:j,...s.skillBody.length>0?{skillBody:s.skillBody}:{}};try{w.add(C),l.success(`Agent "${s.skill.name}" 注册成功`),k(s.skill.name,s.skill.env,o.env)}catch(e){l.error(e instanceof Error?e.message:String(e)),process.exitCode=1}}});function k(e,t,r){const i=s(e,t,r);if(i)return i.missingRequired.length>0?(l.warn(`Agent "${e}" 仍缺少必填环境变量: ${i.missingRequired.map(e=>e.name).join(", ")}`),l.info(`运行 \`roll config setup agent ${e}\` 交互式配置。`),void l.info(`运行 \`roll config explain agents.env.${e}\` 查看配置说明。`)):void(i.processEnvOnlyRequired.length>0&&(l.warn(`Agent "${e}" 当前依赖 shell 环境变量: ${i.processEnvOnlyRequired.map(e=>e.name).join(", ")}`),l.info(`建议运行 \`roll config setup agent ${e}\` 持久写入 roll.config.yaml。`)))}
+import{defineCommand as e}from"citty";import{resolve as t}from"node:path";import{existsSync as r}from"node:fs";import{inspectAgentEnvRequirements as i}from"../../config/helpers.js";import{loadAgentsConfig as o}from"../../config/loader.js";import{discoverAgent as s}from"../../registry/discovery.js";import{writeRemoteSkillManifest as n}from"../../registry/manifest.js";import{AgentStore as a}from"../../registry/store.js";import{cloneOrPullRepo as p,isGitUrl as m,repoNameFromUrl as c}from"../utils/git-source.js";import{log as d}from"../utils/output.js";import{reportAgentEnvGuidance as l}from"./agent-env-guidance.js";import{createInstallCommand as g,detectInstallCommand as f,formatPackageManagerCommand as u,formatPackageManagerError as y,runPackageManager as h}from"../utils/package-manager.js";export default e({meta:{description:"注册本地目录、Git 仓库或远程 MCP endpoint"},args:{path:{type:"positional",description:"本地 Agent 目录或 Git 仓库 URL；远程 endpoint 请用 --remote",required:!1},remote:{type:"string",description:"远程 MCP endpoint；需要同时提供 --name 和 --description"},name:{type:"string",description:"远程 Agent 名称（仅 --remote 时使用）"},description:{type:"string",description:"远程 Agent 描述（仅 --remote 时使用）"}},async run({args:e}){const{agentsConfig:k}=o();let L;if(e.remote){if(!e.name||!e.description)return d.error("远程注册需要同时提供 --name 和 --description"),void(process.exitCode=1);L=n({dataDir:k.dataDir,name:e.name,description:e.description,endpoint:e.remote})}else{if(!e.path)return d.error("请提供本地路径、Git URL，或使用 --remote <endpoint> 注册远程 Agent"),void(process.exitCode=1);if(m(e.path)){const i=c(e.path),o=t(k.dataDir,"repos",i),s=r(o);s?d.info(`仓库目录已存在，拉取最新代码: ${o}`):d.info(`克隆 ${e.path}...`);try{const{action:t}=await p(e.path,o);"cloned"===t&&d.success("克隆完成")}catch(e){return d.error(`${s?"git pull":"git clone"} 失败: ${e instanceof Error?e.message:String(e)}`),void(process.exitCode=1)}L=o}else if(L=t(e.path),!r(L))return d.error(`路径不存在: ${L}`),void(process.exitCode=1)}d.info("解析 SKILL.md...");const $=s(L);d.debug(`名称: ${$.skill.name}`),d.debug(`描述: ${$.skill.description}`),d.debug(`传输: ${$.transport.type}`);const j=t(L,"package.json"),v="1"===process.env.ROLL_SKIP_INSTALL;if(e.remote)d.info("远程 Agent 使用本地 manifest，无需安装依赖。");else if(r(j)&&!v){const e=f(L)??g("pnpm");d.info(`安装依赖 (${u(e)})...`);try{await h(e,{cwd:L}),d.success("依赖安装完成")}catch(t){return d.error(`依赖安装失败: ${y(e,t)}`),void(process.exitCode=1)}}else r(j)&&v&&d.warn("检测到 ROLL_SKIP_INSTALL=1，跳过依赖安装。");const A=e.remote?{type:"remote-manifest",endpoint:e.remote}:e.path&&m(e.path)?{type:"git",url:e.path}:{type:"local-path",path:L},C=new a(k.dataDir),S={skill:$.skill,transport:$.transport,runtime:$.runtime,installPath:L,registeredAt:(new Date).toISOString(),status:"idle",source:A,...$.skillBody.length>0?{skillBody:$.skillBody}:{}};try{C.add(S),d.success(`Agent "${$.skill.name}" 注册成功`),l($.skill.name,i($.skill.name,$.skill.env,k.env))}catch(e){d.error(e instanceof Error?e.message:String(e)),process.exitCode=1}}});

package/dist/cli/commands/agent-env-guidance.d.ts

@@ -0,0 +1,2 @@
+import type { AgentEnvCheckReport } from "../../config/helpers.ts";
+export declare function reportAgentEnvGuidance(agentName: string, envReport: AgentEnvCheckReport | undefined): void;

package/dist/cli/commands/agent-env-guidance.js

@@ -0,0 +1 @@
+import{log as n}from"../utils/output.js";export function reportAgentEnvGuidance(e,i){if(i)return i.missingRequired.length>0?(n.warn(`Agent "${e}" 仍缺少必填环境变量: ${i.missingRequired.map(n=>n.name).join(", ")}`),n.info(`运行 \`roll config setup agent ${e}\` 交互式配置。`),void n.info(`运行 \`roll config explain agents.env.${e}\` 查看配置说明。`)):void(i.processEnvOnlyRequired.length>0&&(n.warn(`Agent "${e}" 当前依赖 shell 环境变量: ${i.processEnvOnlyRequired.map(n=>n.name).join(", ")}`),n.info(`建议运行 \`roll config setup agent ${e}\` 持久写入 roll.config.yaml。`)))}

package/dist/cli/commands/agent-install.d.ts

@@ -14,5 +14,10 @@ declare const _default: import("citty").CommandDef<{
         description: string;
         default: true;
     };
+    force: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
 }>;
 export default _default;

package/dist/cli/commands/agent-install.js

@@ -1 +1 @@
-import{defineCommand as e}from"citty";import{existsSync as t,mkdirSync as r,statSync as i}from"node:fs";import{resolve as s}from"node:path";import{getAgentEnv as n,inspectAgentEnvRequirements as o}from"../../config/helpers.js";import{loadAgentsConfig as a,loadConfig as l,loadInstallConfig as p}from"../../config/loader.js";import{discoverAgent as m}from"../../registry/discovery.js";import{startAgent as c,stopAgentGracefully as g,waitForAgentReady as d}from"../../registry/process-manager.js";import{runAgentSetup as u}from"../../registry/runtime-setup.js";import{AgentStore as f}from"../../registry/store.js";import{parsePackageName as y,readInstalledPackageManifest as k,resolveInstalledPackageRoot as h,sanitizeInstallId as w}from"../../registry/source.js";import{log as $}from"../utils/output.js";import{buildNpmRetryPolicy as v,formatPackageManagerError as j,npmInstallNetworkArgs as C,runPackageManagerWithRetry as S}from"../utils/package-manager.js";function b(e){return C({...e.registry?{registry:e.registry}:{},fetchRetries:e.fetchRetries,preferOffline:e.preferOffline})}function x(e){return e.startsWith("git@")||e.startsWith("git+")||e.startsWith("github:")||e.startsWith("gitlab:")||e.startsWith("bitbucket:")||e.endsWith(".git")}export default e({meta:{description:"安装已发布的 Agent npm 包并注册到本地"},args:{package:{type:"positional",description:"npm 包名、版本范围或 .tgz 路径（源码目录请用 roll agent add）",required:!0},"skip-browser-setup":{type:"boolean",description:"跳过 Playwright 浏览器运行时安装/校验",default:!1},start:{type:"boolean",description:"安装后不自动启动 core-managed Agent",default:!0}},async run({args:e}){const{agentsConfig:o}=a();let C;try{C=p().installConfig}catch(e){return $.error(`install 配置无效，已停止安装：${e instanceof Error?e.message:String(e)}`),void(process.exitCode=1)}const R=e.package;if(x(R))return $.error(`Git URL 请使用 \`roll agent add ${R}\` 注册，不要使用 \`roll agent install\``),void(process.exitCode=1);const D=s(R);if(t(D)&&i(D).isDirectory())return $.error(`本地源码目录请使用 \`roll agent add ${R}\` 注册，不要使用 \`roll agent install\``),void(process.exitCode=1);const W=y(R),q=s(o.dataDir,"installed",w(W));t(q)||r(q,{recursive:!0}),C.registry&&$.info(`使用 npm registry: ${C.registry}（roll.config.yaml install.registry）`),$.info(`安装 ${R}...`);const B={command:"npm",args:["install","--prefix",q,R,...b(C)]};try{await S(B,{timeout:C.networkTimeoutMs},{...v(C.fetchRetries),onRetry:({attempt:e,delayMs:t})=>{$.warn(`安装遇到网络问题，${Math.round(t/1e3)}s 后重试（第 ${e+1} 次）...`)}})}catch(e){return $.error(`安装失败: ${j(B,e)}`),void(process.exitCode=1)}const E=h(q,W);if(!t(E))return $.error(`安装完成但未找到包目录: ${E}`),void(process.exitCode=1);const M=k(E);$.info("解析已安装 Agent 的 SKILL.md...");const O=m(E),L=new f(o.dataDir),T={skill:O.skill,transport:O.transport,runtime:O.runtime,installPath:E,registeredAt:(new Date).toISOString(),status:"idle",source:{type:"installed-package",packageName:M?.name??W,packageSpec:R,installDir:q,...M?.version?{installedVersion:M.version}:{}},...O.skillBody.length>0?{skillBody:O.skillBody}:{}};"core-managed"===T.runtime.ownership&&T.runtime.setup?.playwright&&!e["skip-browser-setup"]&&$.info(`即将安装浏览器运行时 (${T.runtime.setup.playwright.browsers.join(", ")})，这可能需要一些时间...`);const I=await u(T,{skipBrowserSetup:e["skip-browser-setup"]});I.ok?I.skipped?$.info(I.message):$.success(I.message):($.warn(`Agent setup 失败：${I.message}`),I.retryCommand&&$.info(`重试命令: ${I.retryCommand}`));const N=L.findByName(O.skill.name);try{const t="core-managed"===N?.runtime.ownership&&"online"===N.status;if("installed-package"===N?.source?.type?L.replace(N.skill.name,T):L.add(T),!I.ok)return L.updateStatus(O.skill.name,"error"),void(process.exitCode=1);if("core-managed"===T.runtime.ownership&&e.start){t&&await g(o.dataDir,T.skill.name),L.updateStatus(T.skill.name,"starting");let e=!1;try{c(T,o.dataDir,n(l().config,T.skill.name)),e=!0,await d(T,{startupTimeoutMs:15e3,probeTimeoutMs:2e3}),L.updateStatus(T.skill.name,"online")}catch(t){return e&&await g(o.dataDir,T.skill.name).catch(()=>{}),L.updateStatus(T.skill.name,"error"),$.error(`Agent "${O.skill.name}" 已安装，但自动启动失败：${t instanceof Error?t.message:String(t)}`),void(process.exitCode=1)}}$.success(`Agent "${O.skill.name}" 安装并注册成功`),A(O.skill.name,O.skill.env,o.env)}catch(e){$.error(e instanceof Error?e.message:String(e)),process.exitCode=1}}});function A(e,t,r){const i=o(e,t,r);if(i)return i.missingRequired.length>0?($.warn(`Agent "${e}" 仍缺少必填环境变量: ${i.missingRequired.map(e=>e.name).join(", ")}`),$.info(`运行 \`roll config setup agent ${e}\` 交互式配置。`),void $.info(`运行 \`roll config explain agents.env.${e}\` 查看配置说明。`)):void(i.processEnvOnlyRequired.length>0&&($.warn(`Agent "${e}" 当前依赖 shell 环境变量: ${i.processEnvOnlyRequired.map(e=>e.name).join(", ")}`),$.info(`建议运行 \`roll config setup agent ${e}\` 持久写入 roll.config.yaml。`)))}
+import{defineCommand as e}from"citty";import{getAgentEnv as t}from"../../config/helpers.js";import{loadAgentsConfig as r,loadConfig as o,loadInstallConfig as s}from"../../config/loader.js";import{catalogPackageSpec as a,findCatalogEntry as n}from"../../registry/catalog.js";import{resolveAgentCatalog as i}from"../../registry/catalog-discovery.js";import{installAgent as p}from"../../registry/install.js";import{log as g}from"../utils/output.js";import{reportAgentEnvGuidance as c}from"./agent-env-guidance.js";function l(e){if("retry"===e.type)return void g.warn(`安装遇到网络问题，${Math.round(e.delayMs/1e3)}s 后重试（第 ${e.attempt+1} 次）...`);({step:g.info,info:g.info,warn:g.warn,success:g.success})[e.type](e.message)}function m(e){if("setup"===e.step)return g.warn(`Agent setup 失败：${e.message}`),void(e.retryCommand&&g.info(`重试命令: ${e.retryCommand}`));g.error(e.message)}export default e({meta:{description:"安装已发布的 Agent npm 包并注册到本地"},args:{package:{type:"positional",description:"官方 Agent 短名（roll agent list --available 查看）、npm 包名、版本范围或 .tgz 路径（源码目录请用 roll agent add）",required:!0},"skip-browser-setup":{type:"boolean",description:"跳过 Playwright 浏览器运行时安装/校验",default:!1},start:{type:"boolean",description:"安装后自动启动 core-managed Agent（可用 --no-start 跳过）",default:!0},force:{type:"boolean",description:"确认风险并替换同名的非 npm 来源 Agent",default:!1}},async run({args:e}){const{agentsConfig:f}=r();let d;try{d=s().installConfig}catch(e){return g.error(`install 配置无效，已停止安装：${e instanceof Error?e.message:String(e)}`),void(process.exitCode=1)}const u=await i(void 0,{...d.registry?{registry:d.registry}:{}}),y=n(u,e.package),k=y?a(y.entry,y.versionSpec):e.package;y&&k!==e.package&&g.info(`已识别官方 Agent 短名：${e.package} → ${k}`);const v=await p({packageSpec:k,skipBrowserSetup:e["skip-browser-setup"],autoStart:e.start,replaceExisting:e.force,...y?{expectedSkillName:y.entry.skillName}:{}},{agentsConfig:f,installConfig:d,getStartEnv:e=>t(o().config,e),report:l});if(!v.ok)return m(v),void(process.exitCode=1);g.success(`Agent "${v.agent.skill.name}" 安装并注册成功`),c(v.agent.skill.name,v.envReport)}});

package/dist/cli/commands/agent-list.d.ts

@@ -4,5 +4,10 @@ declare const _default: import("citty").CommandDef<{
         description: string;
         default: false;
     };
+    available: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
 }>;
 export default _default;

package/dist/cli/commands/agent-list.js

@@ -1 +1 @@
-import{defineCommand as t}from"citty";import o from"cli-table3";import{loadAgentsConfig as r}from"../../config/loader.js";import{formatAgentSourceType as n,getAgentLocation as e,inferAgentSourceType as s}from"../../registry/source.js";import{AgentStore as a}from"../../registry/store.js";import{formatLocationForDisplay as i,resolveTerminalColumns as l}from"../utils/terminal.js";const c=6,g=2;export default t({meta:{description:"列出所有已注册 Agent"},args:{json:{type:"boolean",description:"JSON 格式输出",default:!1}},run({args:t}){const{agentsConfig:c}=r(),g=new a(c.dataDir).list();if(t.json)return void console.log(JSON.stringify(g,null,2));if(0===g.length)return void console.log("暂无已注册的 Agent。可使用 `roll agent add <path>`、`roll agent install <package>` 或 `roll agent add --remote <endpoint>`。");const u=m(l()),p=new o({head:["Name","Status","Source","Transport","Location"],colWidths:[...u],truncate:"…",style:{head:["cyan"]}});for(const t of g)p.push([t.skill.name,t.status,n(s(t)),t.transport.type,i(e(t),f(u[4]))]);console.log(p.toString())}});function m(t){const o=t-6,r=o-43-24;if(r>=15)return[24,10,14,19,r];const n=Math.max(16,o-43-15);return[n,10,14,19,o-43-n]}function f(t){return Math.max(1,t-2)}
+import{defineCommand as t}from"citty";import e from"chalk";import n from"cli-table3";import{loadAgentsConfig as o,loadInstallConfig as r}from"../../config/loader.js";import{resolveAgentCatalog as s}from"../../registry/catalog-discovery.js";import{formatAgentSourceType as a,getAgentLocation as i,inferAgentSourceType as l}from"../../registry/source.js";import{AgentStore as c}from"../../registry/store.js";import{inspectCatalogAvailability as d}from"../utils/catalog-status.js";import{formatLocationForDisplay as g,resolveTerminalColumns as u}from"../utils/terminal.js";const m=6,p=2;export default t({meta:{description:"列出所有已注册 Agent"},args:{json:{type:"boolean",description:"JSON 格式输出",default:!1},available:{type:"boolean",description:"列出官方 catalog 中可安装的 Agent 及安装状态",default:!1}},async run({args:t}){const{agentsConfig:e}=o(),r=new c(e.dataDir).list();if(t.available)return void await y(r,t.json);if(t.json)return void console.log(JSON.stringify(r,null,2));if(0===r.length)return void console.log("暂无已注册的 Agent。可使用 `roll agent add <path>`、`roll agent install <package>` 或 `roll agent add --remote <endpoint>`。");const s=h(u()),d=new n({head:["Name","Status","Source","Transport","Location"],colWidths:[...s],truncate:"…",style:{head:["cyan"]}});for(const t of r)d.push([t.skill.name,t.status,a(l(t)),t.transport.type,g(i(t),v(s[4]))]);console.log(d.toString())}});const f={"not-installed":t=>e.yellow("未安装")+(t.latestVersion?e.dim(` · 最新 v${t.latestVersion}`):""),installed:t=>{const n="installed-package"===t.installedAgent?.source?.type?t.installedAgent.source.installedVersion:void 0,o=e.green("已安装"+(n?` v${n}`:""));return"update-available"===t.update?.status&&t.latestVersion?`${o} ${e.yellow(`⬆ 可更新到 v${t.latestVersion}`)}`:o},"installed-other-source":t=>{const n=t.installedAgent?a(l(t.installedAgent)):"unknown";return e.green("已注册")+e.dim(`（${n} 来源）`)+(t.latestVersion?e.dim(` · npm 最新 v${t.latestVersion}`):"")}};async function y(t,n){let o;try{o=r().installConfig.registry}catch{o=void 0}const a=await s(void 0,{...o?{registry:o}:{}}),i=await d(a,t,{...o?{registry:o}:{}});if(n)return void console.log(JSON.stringify(i,null,2));const l=[];for(const t of i)l.push(`${e.cyan.bold(t.entry.shortName)}  ${e.dim(t.entry.packageName)}  ${f[t.state](t)}`),l.push(`  ${t.entry.description}`),l.push(`  ${e.dim("必需环境变量:")} ${t.entry.requiredEnv.length>0?t.entry.requiredEnv.join(", "):e.dim("安装后由 SKILL.md 声明")}`),l.push("");l.push("使用 `roll agent install <name>` 安装官方 Agent。"),console.log(l.join("\n"))}function h(t){const e=t-6,n=e-43-24;if(n>=15)return[24,10,14,19,n];const o=Math.max(16,e-43-15);return[o,10,14,19,e-43-o]}function v(t){return Math.max(1,t-2)}

package/dist/cli/commands/chat.d.ts

@@ -1,6 +1,8 @@
 import type { AgentSession } from "@roll-agent/runtime";
 import { type ChatConfirm } from "../utils/chat-renderer.ts";
 import type { ChatCommandResult } from "../../types/chat.ts";
+import type { RollConfig } from "../../config/schema.ts";
+import type { LlmConfigReadiness } from "../../config/helpers.ts";
 type RuntimeModule = typeof import("@roll-agent/runtime");
 type ThreadStoreInstance = InstanceType<RuntimeModule["ThreadStore"]>;
 interface ReplIo {
@@ -8,6 +10,7 @@ interface ReplIo {
     readonly output: NodeJS.WritableStream;
     readonly confirm?: ChatConfirm;
 }
+export declare function resolveChatLlmReadiness(config: RollConfig): LlmConfigReadiness;
 export declare function runJsonTurn(session: AgentSession, message: string): Promise<ChatCommandResult>;
 export declare function runRepl(session: AgentSession, store: ThreadStoreInstance, isNewSession: boolean, io?: ReplIo): Promise<void>;
 declare const _default: import("citty").CommandDef<{

package/dist/cli/commands/chat.js

@@ -1 +1 @@
-import{defineCommand as e}from"citty";import{loadConfig as t}from"../../config/loader.js";import{resolveLLMCall as o,thinkingProviderOptions as n}from"../../llm/providers.js";import{createInterface as s}from"node:readline/promises";import i from"chalk";import r from"cli-table3";import{isDebugLogEnabled as a,log as l}from"../utils/output.js";import{ChatRenderer as c,clackConfirm as d}from"../utils/chat-renderer.js";import{titleFromMessage as u}from"../chat/title.js";import{buildBannerLines as p,renderBannerText as m}from"../chat/banner.js";import{getCurrentVersion as g}from"../utils/update-checker.js";import{buildSkillInvocationPrompt as f,formatSkillList as h,parseSkillInvocation as v}from"../chat/ink/commands.js";const w=import.meta.url.endsWith(".ts")?"ts":"js";function y(e,t){return new e.ConfigurableToolPolicy({defaultMode:t.runtime.approval.default,overrides:t.runtime.approval.overrides})}function k(e){console.log(JSON.stringify(e,null,2))}function b(e){l.warn(`Agent "${e.agentName}" 启动失败：${e.message}`)}function S(e){l.warn(`skill 目录加载警告：${e}`)}function x(e,t){const o=v(t,e.getSkillSummaries());return o&&o.prompt.length>0?f(o):t}async function C(e,t,o){l.debug(`chat.repl input waiting · ${o}`),e.resume();try{const n=await e.question(t);return l.debug(`chat.repl input received · ${o} · chars=${String(n.length)}`),n}catch(e){const t=e instanceof Error?e.message:String(e);return void l.debug(`chat.repl input closed · ${o} · ${t}`)}finally{e.pause()}}async function T(){return import("@roll-agent/runtime")}async function I(e){const t=e.runtime.provider??e.llm.defaultProvider,n=e.runtime.model??e.llm.defaultModel,s=e.llm.providers[t];if(!s)return l.error(`LLM provider "${t}" 未配置。请检查 roll.config.yaml`),void(process.exitCode=1);const i=await T(),{ConversationEngine:r,ThreadStore:c,RuntimeServer:d,createStdioConnection:u}=i,{model:p,providerOptions:m}=o(t,n,s.apiKey,"chat",s.baseUrl,e.runtime.thinkingLevel),g=new c(e.runtime.threadsDir),f=new r({config:e,model:p,store:g,policy:y(i,e),maxSteps:e.runtime.maxSteps,...m?{providerOptions:m}:{},debugEvents:a(),onAgentBootstrapIssue:b,onSkillLibraryIssue:S}),h=u(process.stdin,process.stdout),v=new d(f,h);h.onClose(()=>{v.abortAll(),f.dispose().catch(()=>{}).finally(()=>{g.close(),process.exit(0)})}),l.info("roll runtime-server 已启动（stdio JSON-RPC，等待客户端连接）")}async function $(e,t){const{ThreadStore:o}=await T(),n=new o(e.runtime.threadsDir);try{const e=n.listThreads();if(t){const t=e.map(e=>({...e,messageCount:n.countMessages(e.id)}));return void console.log(JSON.stringify(t,null,2))}if(0===e.length)return void console.log('暂无会话。用 `roll chat "<message>"` 开始一个。');const o=new r({head:["Session ID","标题","消息","更新时间"],style:{head:["cyan"]}});for(const t of e)o.push([t.id,t.title??"-",String(n.countMessages(t.id)),t.updatedAt]);console.log(o.toString())}finally{n.close()}}export async function runJsonTurn(e,t){const o=[],n=[],s=[],i=[];let r,a,l,c,d="";for await(const u of e.send(t))switch(u.type){case"text-delta":d+=u.delta;break;case"tool-call":o.push({summary:`${u.agentName}.${u.toolName}`,agentName:u.agentName,toolName:u.toolName});break;case"confirmation-required":i.push({summary:`${u.agentName}.${u.toolName}`,agentName:u.agentName,toolName:u.toolName}),e.reject(u.approvalId,"json 模式不支持交互确认");break;case"step-finish":n.push({finishReason:u.finishReason,...u.usage?{usage:u.usage}:{}});break;case"message-finish":a=u.totalUsage,l=u.sessionUsage,c=u.contextInputTokens;break;case"context-compacted":s.push({reason:u.reason,strategy:u.strategy,removed:u.removed,kept:u.kept,...void 0!==u.truncatedTools?{truncatedTools:u.truncatedTools}:{},...void 0!==u.beforeInputTokens?{beforeInputTokens:u.beforeInputTokens}:{}});break;case"error":r=u.message}const u=e.getContextWindow();return void 0!==r?{status:"failed",stage:"execute",message:r,sessionId:e.id}:i.length>0?{status:"needs_confirmation",sessionId:e.id,message:"存在需要确认的工具调用，请在交互模式下执行或显式批准",pendingActions:i}:{status:"completed",sessionId:e.id,output:d,steps:o,...n.length>0?{stepUsages:n}:{},...a?{totalUsage:a}:{},...l?{sessionUsage:l}:{},...void 0!==u?{contextWindow:u}:{},...void 0!==c?{contextInputTokens:c}:{},...s.length>0?{compactions:s}:{}}}export async function runRepl(e,t,o,n={input:process.stdin,output:process.stdout}){const r=s({input:n.input,output:n.output});r.on("SIGINT",()=>r.close());const a=n.confirm??(async e=>{l.debug("chat.repl input waiting · confirm"),r.pause();const t=await d(e);return l.debug(`chat.repl input received · confirm · approved=${String(t)}`),t}),p=new c(a,e.getContextWindow()),m=e.getSkillSummaries();l.info("进入多轮对话（输入 exit / quit 或 Ctrl-C 退出，/compact 手动压缩上下文）");let g=!o,w=!1;try{for(;;){const o=await C(r,i.green("› "),"prompt");if(void 0===o)break;const n=o.trim();if(0===n.length)continue;if("exit"===n||"quit"===n)break;if("/compact"===n){l.debug("chat.repl manual compact requested");for await(const t of e.compact("manual"))await p.handle(t,e);l.debug("chat.repl manual compact completed");continue}if("/skills"===n){l.info(h(m,(process.stdout.columns||96)-2));continue}const s=v(n,m);if(s&&0===s.prompt.length){l.info("用法: /<skill-name> [/<skill-name> ...] 你的请求");continue}const a=s?f(s):n;g||(t.updateTitle(e.id,u(n)),g=!0),w=!0,l.debug(`chat.repl send start · chars=${String(n.length)}`);for await(const t of e.send(a))await p.handle(t,e);l.debug("chat.repl send completed")}}finally{r.close(),o&&!w&&0===t.countMessages(e.id)&&t.deleteThread(e.id)}}export default e({meta:{description:"会话式 AI 助手（多轮对话 + 自动工具调用）"},args:{message:{type:"positional",description:"起始消息",required:!1},session:{type:"string",description:"继续已有会话的 session ID"},last:{type:"boolean",description:"继续最近一个会话",default:!1},list:{type:"boolean",description:"列出已有会话",default:!1},json:{type:"boolean",description:"JSON 格式输出",default:!1},server:{type:"boolean",description:"以 JSON-RPC daemon 模式运行（stdio，供 GUI/前端接入）",default:!1}},async run({args:e}){const{config:s}=t();if(e.server)return void await I(s);if(e.list)return void await $(s,e.json);const i=s.runtime.provider??s.llm.defaultProvider,r=s.runtime.model??s.llm.defaultModel,f=s.llm.providers[i];if(!f)return l.error(`LLM provider "${i}" 未配置。请检查 roll.config.yaml`),void(process.exitCode=1);if(e.json&&!e.message)return l.error('--json 模式需要消息：roll chat "<message>" --json'),void(process.exitCode=1);const h=await T(),{ConversationEngine:v,ThreadStore:C}=h,{model:N,providerOptions:j}=o(i,r,f.apiKey,"chat",f.baseUrl,s.runtime.thinkingLevel),L=new C(s.runtime.threadsDir),O=new v({config:s,model:N,store:L,policy:y(h,s),maxSteps:s.runtime.maxSteps,...j?{providerOptions:j}:{},debugEvents:a(),onAgentBootstrapIssue:b,onSkillLibraryIssue:S});try{let t;if(e.session)t=await O.resumeSession(e.session);else if(e.last){const e=L.listThreads()[0];if(!e)return l.error('暂无可继续的会话，先用 `roll chat "<message>"` 开始一个'),void(process.exitCode=1);t=await O.resumeSession(e.id)}else t=await O.createSession(e.message?{title:u(e.message)}:{});if(e.json&&e.message){const o=await runJsonTurn(t,x(t,e.message));return k(o),void("completed"!==o.status&&(process.exitCode=1))}if(l.info(`会话 ${t.id}`),s.runtime.compaction.enabled&&void 0===t.getContextWindow()&&l.warn(`未知模型 "${r}" 的 context window，阈值自动压缩不可用。可在 roll.config.yaml 设置 runtime.context-window`),e.message){const o=new c(d,t.getContextWindow());for await(const n of t.send(x(t,e.message)))await o.handle(n,t)}else{const o=!e.session&&!e.last,a=Boolean(process.stdout.isTTY&&process.stdin.isTTY&&"function"==typeof process.stdin.setRawMode),c=await O.getContextSummary(),d={version:g(),model:r,agentCount:c.agentCount,skillCount:c.skillCount};let u=!1;if(a)try{const e=new URL(`../chat/ink/run-ink-repl.${w}`,import.meta.url).href,{runInkRepl:a}=await import(e);await a(t,L,o,{model:r,banner:d,initialThinkingLevel:s.runtime.thinkingLevel,onThinkingChange:e=>t.setProviderOptions(n(i,r,e))}),u=!0}catch(e){l.warn(`Ink TUI 不可用，回退到基础多轮模式：${e instanceof Error?e.message:String(e)}`)}u||(process.stderr.write(`${m(p(d,process.stdout.columns||80))}\n`),await runRepl(t,L,o))}}catch(e){l.error(e instanceof Error?e.message:String(e)),process.exitCode=1}finally{await O.dispose(),L.close()}}});
+var e=this&&this.__rewriteRelativeImportExtension||function(e,t){return"string"==typeof e&&/^\.\.?\//.test(e)?e.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i,function(e,o,s,n,i){return o?t?".jsx":".js":!s||n&&i?s+n+"."+i.toLowerCase()+"js":e}):e};import{defineCommand as t}from"citty";import{inspectLlmConfigReadiness as o}from"../../config/helpers.js";import{loadConfig as s}from"../../config/loader.js";import{resolveLLMCall as n,thinkingProviderOptions as i}from"../../llm/providers.js";import{createInterface as r}from"node:readline/promises";import a from"chalk";import l from"cli-table3";import{isDebugLogEnabled as c,log as d}from"../utils/output.js";import{ChatRenderer as u,clackConfirm as p}from"../utils/chat-renderer.js";import{titleFromMessage as m}from"../chat/title.js";import{buildBannerLines as g,renderBannerText as f}from"../chat/banner.js";import{getCurrentVersion as h}from"../utils/update-checker.js";import{buildSkillInvocationPrompt as v,formatSkillList as w,parseSkillInvocation as y}from"../chat/ink/commands.js";const b=import.meta.url.endsWith(".ts")?"ts":"js";function k(e,t){return new e.ConfigurableToolPolicy({defaultMode:t.runtime.approval.default,overrides:t.runtime.approval.overrides})}function C(e){console.log(JSON.stringify(e,null,2))}function x(e){d.warn(`Agent "${e.agentName}" 启动失败：${e.message}`)}function S(e){d.warn(`skill 目录加载警告：${e}`)}function T(e,t){const o=y(t,e.getSkillSummaries());return o&&o.prompt.length>0?v(o):t}async function I(e,t,o){d.debug(`chat.repl input waiting · ${o}`),e.resume();try{const s=await e.question(t);return d.debug(`chat.repl input received · ${o} · chars=${String(s.length)}`),s}catch(e){const t=e instanceof Error?e.message:String(e);return void d.debug(`chat.repl input closed · ${o} · ${t}`)}finally{e.pause()}}async function j(){return import("@roll-agent/runtime")}async function $(t,o){const s=new URL(`./setup.${b}`,import.meta.url).href;return(await import(e(s))).runChatOnboarding({},{provider:t,model:o})}export function resolveChatLlmReadiness(e){return o(e,{provider:e.runtime.provider??e.llm.defaultProvider,model:e.runtime.model??e.llm.defaultModel})}async function N(e){const t=resolveChatLlmReadiness(e);if(!t.configured||!t.providerConfig)return d.error(t.message),void(process.exitCode=1);const o=t.providerConfig,s=t.provider,i=t.model,r=await j(),{ConversationEngine:a,ThreadStore:l,RuntimeServer:u,createStdioConnection:p}=r,{model:m,providerOptions:g}=n(s,i,o.apiKey,"chat",o.baseUrl,e.runtime.thinkingLevel),f=new l(e.runtime.threadsDir),h=new a({config:e,model:m,store:f,policy:k(r,e),maxSteps:e.runtime.maxSteps,...g?{providerOptions:g}:{},debugEvents:c(),onAgentBootstrapIssue:x,onSkillLibraryIssue:S}),v=p(process.stdin,process.stdout),w=new u(h,v);v.onClose(()=>{w.abortAll(),h.dispose().catch(()=>{}).finally(()=>{f.close(),process.exit(0)})}),d.info("roll runtime-server 已启动（stdio JSON-RPC，等待客户端连接）")}async function R(e,t){const{ThreadStore:o}=await j(),s=new o(e.runtime.threadsDir);try{const e=s.listThreads();if(t){const t=e.map(e=>({...e,messageCount:s.countMessages(e.id)}));return void console.log(JSON.stringify(t,null,2))}if(0===e.length)return void console.log('暂无会话。用 `roll chat "<message>"` 开始一个。');const o=new l({head:["Session ID","标题","消息","更新时间"],style:{head:["cyan"]}});for(const t of e)o.push([t.id,t.title??"-",String(s.countMessages(t.id)),t.updatedAt]);console.log(o.toString())}finally{s.close()}}export async function runJsonTurn(e,t){const o=[],s=[],n=[],i=[];let r,a,l,c,d="";for await(const u of e.send(t))switch(u.type){case"text-delta":d+=u.delta;break;case"tool-call":o.push({summary:`${u.agentName}.${u.toolName}`,agentName:u.agentName,toolName:u.toolName});break;case"confirmation-required":i.push({summary:`${u.agentName}.${u.toolName}`,agentName:u.agentName,toolName:u.toolName}),e.reject(u.approvalId,"json 模式不支持交互确认");break;case"step-finish":s.push({finishReason:u.finishReason,...u.usage?{usage:u.usage}:{}});break;case"message-finish":a=u.totalUsage,l=u.sessionUsage,c=u.contextInputTokens;break;case"context-compacted":n.push({reason:u.reason,strategy:u.strategy,removed:u.removed,kept:u.kept,...void 0!==u.truncatedTools?{truncatedTools:u.truncatedTools}:{},...void 0!==u.beforeInputTokens?{beforeInputTokens:u.beforeInputTokens}:{}});break;case"error":r=u.message}const u=e.getContextWindow();return void 0!==r?{status:"failed",stage:"execute",message:r,sessionId:e.id}:i.length>0?{status:"needs_confirmation",sessionId:e.id,message:"存在需要确认的工具调用，请在交互模式下执行或显式批准",pendingActions:i}:{status:"completed",sessionId:e.id,output:d,steps:o,...s.length>0?{stepUsages:s}:{},...a?{totalUsage:a}:{},...l?{sessionUsage:l}:{},...void 0!==u?{contextWindow:u}:{},...void 0!==c?{contextInputTokens:c}:{},...n.length>0?{compactions:n}:{}}}export async function runRepl(e,t,o,s={input:process.stdin,output:process.stdout}){const n=r({input:s.input,output:s.output});n.on("SIGINT",()=>n.close());const i=s.confirm??(async e=>{d.debug("chat.repl input waiting · confirm"),n.pause();const t=await p(e);return d.debug(`chat.repl input received · confirm · approved=${String(t)}`),t}),l=new u(i,e.getContextWindow()),c=e.getSkillSummaries();d.info("进入多轮对话（输入 exit / quit 或 Ctrl-C 退出，/compact 手动压缩上下文）");let g=!o,f=!1;try{for(;;){const o=await I(n,a.green("› "),"prompt");if(void 0===o)break;const s=o.trim();if(0===s.length)continue;if("exit"===s||"quit"===s)break;if("/compact"===s){d.debug("chat.repl manual compact requested");for await(const t of e.compact("manual"))await l.handle(t,e);d.debug("chat.repl manual compact completed");continue}if("/skills"===s){d.info(w(c,(process.stdout.columns||96)-2));continue}const i=y(s,c);if(i&&0===i.prompt.length){d.info("用法: /<skill-name> [/<skill-name> ...] 你的请求");continue}const r=i?v(i):s;g||(t.updateTitle(e.id,m(s)),g=!0),f=!0,d.debug(`chat.repl send start · chars=${String(s.length)}`);for await(const t of e.send(r))await l.handle(t,e);d.debug("chat.repl send completed")}}finally{n.close(),o&&!f&&0===t.countMessages(e.id)&&t.deleteThread(e.id)}}export default t({meta:{description:"会话式 AI 助手（多轮对话 + 自动工具调用）"},args:{message:{type:"positional",description:"起始消息",required:!1},session:{type:"string",description:"继续已有会话的 session ID"},last:{type:"boolean",description:"继续最近一个会话",default:!1},list:{type:"boolean",description:"列出已有会话",default:!1},json:{type:"boolean",description:"JSON 格式输出",default:!1},server:{type:"boolean",description:"以 JSON-RPC daemon 模式运行（stdio，供 GUI/前端接入）",default:!1}},async run({args:e}){let{config:t}=s();if(e.server)return void await N(t);if(e.list)return void await R(t,e.json);let o=resolveChatLlmReadiness(t);if(!o.configured){!0===process.stdin.isTTY&&!0===process.stderr.isTTY&&!e.json&&await $(o.provider,o.model)&&(t=s().config,o=resolveChatLlmReadiness(t))}if(!o.configured||!o.providerConfig)return d.error(o.message),void(process.exitCode=1);const r=o.providerConfig,a=o.provider,l=o.model;if(e.json&&!e.message)return d.error('--json 模式需要消息：roll chat "<message>" --json'),void(process.exitCode=1);const v=await j(),{ConversationEngine:w,ThreadStore:y}=v,{model:I,providerOptions:L}=n(a,l,r.apiKey,"chat",r.baseUrl,t.runtime.thinkingLevel),O=new y(t.runtime.threadsDir),U=new w({config:t,model:I,store:O,policy:k(v,t),maxSteps:t.runtime.maxSteps,...L?{providerOptions:L}:{},debugEvents:c(),onAgentBootstrapIssue:x,onSkillLibraryIssue:S,sessionExecEnabled:void 0===e.message});let E;try{let o;if(e.session)o=await U.resumeSession(e.session);else if(e.last){const e=O.listThreads()[0];if(!e)return d.error('暂无可继续的会话，先用 `roll chat "<message>"` 开始一个'),void(process.exitCode=1);o=await U.resumeSession(e.id)}else o=await U.createSession(e.message?{title:m(e.message)}:{});if(E=o,e.json&&e.message){const t=await runJsonTurn(o,T(o,e.message));return C(t),void("completed"!==t.status&&(process.exitCode=1))}if(d.info(`会话 ${o.id}`),t.runtime.compaction.enabled&&void 0===o.getContextWindow()&&d.warn(`未知模型 "${l}" 的 context window，阈值自动压缩不可用。可在 roll.config.yaml 设置 runtime.context-window`),e.message){const t=new u(p,o.getContextWindow());for await(const s of o.send(T(o,e.message)))await t.handle(s,o)}else{const s=!e.session&&!e.last,n=Boolean(process.stdout.isTTY&&process.stdin.isTTY&&"function"==typeof process.stdin.setRawMode),r=await U.getContextSummary(),c={version:h(),model:l,agentCount:r.agentCount,skillCount:r.skillCount};let u=!1;if(n)try{const e=new URL(`../chat/ink/run-ink-repl.${b}`,import.meta.url).href,{runInkRepl:n}=await import(e);await n(o,O,s,{model:l,banner:c,initialThinkingLevel:t.runtime.thinkingLevel,onThinkingChange:e=>o.setProviderOptions(i(a,l,e))}),u=!0}catch(e){d.warn(`Ink TUI 不可用，回退到基础多轮模式：${e instanceof Error?e.message:String(e)}`)}u||(process.stderr.write(`${f(g(c,process.stdout.columns||80))}\n`),await runRepl(o,O,s))}}catch(e){d.error(e instanceof Error?e.message:String(e)),process.exitCode=1}finally{E?.abort(),await U.dispose(),O.close()}}});

package/dist/cli/commands/config-guidance.d.ts

@@ -100,6 +100,27 @@ export declare const CONFIG_GUIDANCE_ENTRIES: readonly [{
     readonly purpose: "`roll chat` 按完整 `agentName.toolName` 覆盖单个工具的确认策略。可选值为 `auto`、`confirm`、`deny`。";
     readonly defaultBehavior: "未配置时回退到 `runtime.approval.default`。";
     readonly example: "runtime:\n  approval:\n    overrides:\n      browser-use-agent.zhipin_send_prepared_reply: confirm\n      browser-use-agent.browser_status: auto";
+}, {
+    readonly path: "runtime.shell.enabled";
+    readonly title: "Chat 内建 shell 工具";
+    readonly purpose: "开启后 `roll chat` 注册内建 shell 工具：macOS/Linux 为 `roll__bash`，Windows 原生为 `roll__powershell`（需 PowerShell 7+）。命令继承 roll 进程环境变量；默认确认策略可由 `runtime.approval` 及精确 override 覆盖。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\uFF08\u5173\u95ED\uFF09\u3002Windows \u672A\u68C0\u6D4B\u5230 pwsh 7+ \u65F6\u4F1A\u8DF3\u8FC7\u6CE8\u518C\u3002`;
+    readonly example: "runtime:\n  shell:\n    enabled: true";
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "runtime.shell.auto-approve-safe";
+    readonly title: "只读命令免确认";
+    readonly purpose: "开启后用内建规则分类器识别 POSIX known-safe 只读命令（如 `ls`、`cat`、`git status`），在 `guarded`/`auto` 策略下免确认执行；dangerous（`rm -rf`、`sudo`）与无法识别的命令默认仍需确认。工具级显式 approval override 优先；Windows PowerShell 当前全部按 unknown 处理。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\u3002\u5173\u95ED\u540E POSIX \u56DE\u5F52\u9ED8\u8BA4\u9010\u6761\u786E\u8BA4\uFF1BWindows PowerShell \u9ED8\u8BA4\u9010\u6761\u786E\u8BA4\uFF0C\u663E\u5F0F approval override \u53EF\u8986\u76D6\u3002`;
+    readonly example: "runtime:\n  shell:\n    enabled: true\n    auto-approve-safe: false";
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "runtime.shell.session.enabled";
+    readonly title: "Chat 会话式长命令执行";
+    readonly purpose: "开启后在 POSIX shell 后端注册 `roll__exec_command` + `roll__exec_poll` 工具：命令在后台会话执行、跨轮存活，模型轮询进度并读取退出码，适合超过单轮超时的长脚本。Windows 原生 session exec 暂未支持。仅交互 REPL 与 `--server` 长驻模式注册（单条消息 / `--json` 单轮会话随进程结束，不提供该工具）；`--server` 下 `exec_command` 需 `runtime.approval.overrides` 里 `roll.exec_command: auto` 显式授权。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\uFF08\u5173\u95ED\uFF09\u3002\u9700\u540C\u65F6\u5F00\u542F runtime.shell.enabled\uFF1B\u80CC\u666F\u4F1A\u8BDD\u968F roll chat \u8FDB\u7A0B\u9000\u51FA\u800C\u7EC8\u6B62\u3002`;
+    readonly example: "runtime:\n  shell:\n    enabled: true\n    session:\n      enabled: true\n  approval:\n    overrides:\n      roll.exec_command: auto";
+    readonly setupCommand: "roll config setup shell";
 }, {
     readonly path: "skills.dirs";
     readonly title: "Chat 额外 skill 目录";

package/dist/cli/commands/config-guidance.js

@@ -1 +1 @@
-import{DEFAULT_CONFIG as e}from"../../config/defaults.js";import{normalizeUserPath as t}from"../../config/key-codec.js";export const INSTALL_SCENARIOS=["default-network","china-dev","private-registry","advanced"];export const CONFIG_GUIDANCE_ENTRIES=[{path:"llm.default-provider",title:"默认 LLM Provider",purpose:"`roll ask` / `roll chat` 默认使用的模型提供商。",defaultBehavior:`默认值为 \`${e.llm.defaultProvider}\`。`,example:`llm:\n  default-provider: ${e.llm.defaultProvider}`,setupCommand:"roll config setup llm"},{path:"llm.default-model",title:"默认 LLM Model",purpose:"`roll ask` / `roll chat` 默认使用的模型名称。",defaultBehavior:`默认值为 \`${e.llm.defaultModel}\`。`,example:`llm:\n  default-model: ${e.llm.defaultModel}`,setupCommand:"roll config setup llm"},{path:"llm.providers.<provider>.api-key",title:"Provider API Key",purpose:"指定 LLM provider 的 API key。可以写真实 key，也可以写 `${ENV_VAR}` 占位符。",example:"llm:\n  providers:\n    anthropic:\n      api-key: ${ANTHROPIC_API_KEY}",setupCommand:"roll config setup llm"},{path:"llm.providers.<provider>.base-url",title:"Provider Base URL",purpose:"指定 LLM provider 的自定义 API base URL，通常只在代理、兼容网关或私有部署时需要。",defaultBehavior:"不配置时使用 provider SDK 默认地址。",example:"llm:\n  providers:\n    openai:\n      base-url: https://api.openai.com/v1",setupCommand:"roll config setup llm"},{path:"install.registry",title:"npm Registry",purpose:"`roll agent install` / `roll update` 查询和安装 npm 包时使用的 registry。",defaultBehavior:"不配置时走 npm 自身默认源；Roll 不做隐式镜像 fallback。",example:"install:\n  registry: https://registry.npmmirror.com",setupCommand:"roll config setup install"},{path:"install.fetch-retries",title:"npm Fetch Retries",purpose:"透传给 npm 的 `--fetch-retries`，同时影响 Roll 层整体网络重试次数。",defaultBehavior:`默认值为 \`${e.install.fetchRetries}\`。`,example:`install:\n  fetch-retries: ${e.install.fetchRetries}`,setupCommand:"roll config setup install"},{path:"install.prefer-offline",title:"Prefer Offline",purpose:"安装时是否附加 `--prefer-offline`。",defaultBehavior:`默认值为 \`${e.install.preferOffline}\`，避免更新时复用过期 npm 元数据。`,example:`install:\n  prefer-offline: ${e.install.preferOffline}`,setupCommand:"roll config setup install"},{path:"install.network-timeout-ms",title:"Install Network Timeout",purpose:"单次 npm install 命令的超时时间，单位毫秒。",defaultBehavior:`默认值为 \`${e.install.networkTimeoutMs}\`，即 120 秒。`,example:`install:\n  network-timeout-ms: ${e.install.networkTimeoutMs}`,setupCommand:"roll config setup install"},{path:"agents.data-dir",title:"Agent 数据目录",purpose:"Roll 持久化已注册 Agent、PID、日志和 runtime sidecar 的目录。",defaultBehavior:`默认值为 \`${e.agents.dataDir}\`。`,example:`agents:\n  data-dir: ${e.agents.dataDir}`},{path:"agents.env.<agent-name>",title:"Agent 环境变量",purpose:"按 Agent 名称声明注入到子 Agent 进程的环境变量。",defaultBehavior:"未配置时只会继承当前 shell 环境变量；core-managed Agent 需要重启才会看到新值。",example:"agents:\n  env:\n    browser-use-agent:\n      REPLY_AUTHORITY_URL: https://example.com",setupCommand:"roll config setup agent <agent-name>"},{path:"ask.confirm-threshold",title:"Ask 确认阈值",purpose:"`roll ask` 路由置信度低于该阈值时，倾向要求用户确认。",defaultBehavior:"未配置时使用内置路由默认行为。",example:"ask:\n  confirm-threshold: 0.5"},{path:"runtime.approval.default",title:"Chat 工具确认默认策略",purpose:"`roll chat` 调用工具时的默认确认策略。`guarded` 使用内置读写启发式，`auto` 默认放行非破坏性工具，`deny` 默认拒绝。",defaultBehavior:`默认值为 \`${e.runtime.approval.default}\`。此配置不影响 \`roll ask\`。`,example:`runtime:\n  approval:\n    default: ${e.runtime.approval.default}`},{path:"runtime.approval.overrides",title:"Chat 工具确认精确覆盖",purpose:"`roll chat` 按完整 `agentName.toolName` 覆盖单个工具的确认策略。可选值为 `auto`、`confirm`、`deny`。",defaultBehavior:"未配置时回退到 `runtime.approval.default`。",example:"runtime:\n  approval:\n    overrides:\n      browser-use-agent.zhipin_send_prepared_reply: confirm\n      browser-use-agent.browser_status: auto"},{path:"skills.dirs",title:"Chat 额外 skill 目录",purpose:"`roll chat` 除自动发现项目与用户级 `.agents/skills`（`npx skills add` 的标准安装位置）及已注册 Agent 的 SKILL.md 外，额外加载的 skill 目录。目录可以直接包含 SKILL.md，也可以是多个 skill 子目录的集合。",defaultBehavior:"默认为空。标准路径 `<项目>/.agents/skills` 与 `~/.agents/skills` 始终自动发现。",example:"skills:\n  dirs:\n    - ./openclaw-roll-core-skill-template"},{path:"browser.default-instance",title:"默认浏览器实例",purpose:"多浏览器实例配置下，未显式指定 browserInstance 时使用的默认实例。",defaultBehavior:"不配置且只有一个实例时可自动推断；多个实例时工具可能返回 needs_input。",example:"browser:\n  default-instance: boss-a"},{path:"browser.instances",title:"浏览器实例声明",purpose:"声明 browser-use-agent 可使用的浏览器 profile、CDP 端口、会话目录和业务归因信息。",defaultBehavior:"不配置时 browser-use-agent 使用 legacy 单实例环境变量路径。",example:"browser:\n  instances:\n    boss-a:\n      platform: zhipin\n      mode: managed-cdp\n      cdp-port: 9222\n      user-data-dir: ~/.roll-agent/browser/boss-a"}];export function listConfigGuidanceEntries(){return CONFIG_GUIDANCE_ENTRIES}export function findConfigGuidance(e){const r=t(e.split(".")).join(".");return CONFIG_GUIDANCE_ENTRIES.find(e=>l(e.path,r))}function l(e,l){const r=t(e.split(".")).join(".");if(r===l)return!0;const a=r.split("."),n=l.split(".");return a.length===n.length&&a.every((e,t)=>e.startsWith("<")||e===n[t])}export function flattenAgentEnvDeclarations(e){return[...(e?.required??[]).map(e=>({...e,required:!0})),...(e?.optional??[]).map(e=>({...e,required:!1}))]}export function isSecretEnvName(e){return/(?:TOKEN|KEY|SECRET|PASSWORD)/iu.test(e)}
+import{DEFAULT_CONFIG as e}from"../../config/defaults.js";import{normalizeUserPath as l}from"../../config/key-codec.js";export const INSTALL_SCENARIOS=["default-network","china-dev","private-registry","advanced"];export const CONFIG_GUIDANCE_ENTRIES=[{path:"llm.default-provider",title:"默认 LLM Provider",purpose:"`roll ask` / `roll chat` 默认使用的模型提供商。",defaultBehavior:`默认值为 \`${e.llm.defaultProvider}\`。`,example:`llm:\n  default-provider: ${e.llm.defaultProvider}`,setupCommand:"roll config setup llm"},{path:"llm.default-model",title:"默认 LLM Model",purpose:"`roll ask` / `roll chat` 默认使用的模型名称。",defaultBehavior:`默认值为 \`${e.llm.defaultModel}\`。`,example:`llm:\n  default-model: ${e.llm.defaultModel}`,setupCommand:"roll config setup llm"},{path:"llm.providers.<provider>.api-key",title:"Provider API Key",purpose:"指定 LLM provider 的 API key。可以写真实 key，也可以写 `${ENV_VAR}` 占位符。",example:"llm:\n  providers:\n    anthropic:\n      api-key: ${ANTHROPIC_API_KEY}",setupCommand:"roll config setup llm"},{path:"llm.providers.<provider>.base-url",title:"Provider Base URL",purpose:"指定 LLM provider 的自定义 API base URL，通常只在代理、兼容网关或私有部署时需要。",defaultBehavior:"不配置时使用 provider SDK 默认地址。",example:"llm:\n  providers:\n    openai:\n      base-url: https://api.openai.com/v1",setupCommand:"roll config setup llm"},{path:"install.registry",title:"npm Registry",purpose:"`roll agent install` / `roll update` 查询和安装 npm 包时使用的 registry。",defaultBehavior:"不配置时走 npm 自身默认源；Roll 不做隐式镜像 fallback。",example:"install:\n  registry: https://registry.npmmirror.com",setupCommand:"roll config setup install"},{path:"install.fetch-retries",title:"npm Fetch Retries",purpose:"透传给 npm 的 `--fetch-retries`，同时影响 Roll 层整体网络重试次数。",defaultBehavior:`默认值为 \`${e.install.fetchRetries}\`。`,example:`install:\n  fetch-retries: ${e.install.fetchRetries}`,setupCommand:"roll config setup install"},{path:"install.prefer-offline",title:"Prefer Offline",purpose:"安装时是否附加 `--prefer-offline`。",defaultBehavior:`默认值为 \`${e.install.preferOffline}\`，避免更新时复用过期 npm 元数据。`,example:`install:\n  prefer-offline: ${e.install.preferOffline}`,setupCommand:"roll config setup install"},{path:"install.network-timeout-ms",title:"Install Network Timeout",purpose:"单次 npm install 命令的超时时间，单位毫秒。",defaultBehavior:`默认值为 \`${e.install.networkTimeoutMs}\`，即 120 秒。`,example:`install:\n  network-timeout-ms: ${e.install.networkTimeoutMs}`,setupCommand:"roll config setup install"},{path:"agents.data-dir",title:"Agent 数据目录",purpose:"Roll 持久化已注册 Agent、PID、日志和 runtime sidecar 的目录。",defaultBehavior:`默认值为 \`${e.agents.dataDir}\`。`,example:`agents:\n  data-dir: ${e.agents.dataDir}`},{path:"agents.env.<agent-name>",title:"Agent 环境变量",purpose:"按 Agent 名称声明注入到子 Agent 进程的环境变量。",defaultBehavior:"未配置时只会继承当前 shell 环境变量；core-managed Agent 需要重启才会看到新值。",example:"agents:\n  env:\n    browser-use-agent:\n      REPLY_AUTHORITY_URL: https://example.com",setupCommand:"roll config setup agent <agent-name>"},{path:"ask.confirm-threshold",title:"Ask 确认阈值",purpose:"`roll ask` 路由置信度低于该阈值时，倾向要求用户确认。",defaultBehavior:"未配置时使用内置路由默认行为。",example:"ask:\n  confirm-threshold: 0.5"},{path:"runtime.approval.default",title:"Chat 工具确认默认策略",purpose:"`roll chat` 调用工具时的默认确认策略。`guarded` 使用内置读写启发式，`auto` 默认放行非破坏性工具，`deny` 默认拒绝。",defaultBehavior:`默认值为 \`${e.runtime.approval.default}\`。此配置不影响 \`roll ask\`。`,example:`runtime:\n  approval:\n    default: ${e.runtime.approval.default}`},{path:"runtime.approval.overrides",title:"Chat 工具确认精确覆盖",purpose:"`roll chat` 按完整 `agentName.toolName` 覆盖单个工具的确认策略。可选值为 `auto`、`confirm`、`deny`。",defaultBehavior:"未配置时回退到 `runtime.approval.default`。",example:"runtime:\n  approval:\n    overrides:\n      browser-use-agent.zhipin_send_prepared_reply: confirm\n      browser-use-agent.browser_status: auto"},{path:"runtime.shell.enabled",title:"Chat 内建 shell 工具",purpose:"开启后 `roll chat` 注册内建 shell 工具：macOS/Linux 为 `roll__bash`，Windows 原生为 `roll__powershell`（需 PowerShell 7+）。命令继承 roll 进程环境变量；默认确认策略可由 `runtime.approval` 及精确 override 覆盖。",defaultBehavior:`默认值为 \`${String(e.runtime.shell.enabled)}\`（关闭）。Windows 未检测到 pwsh 7+ 时会跳过注册。`,example:"runtime:\n  shell:\n    enabled: true",setupCommand:"roll config setup shell"},{path:"runtime.shell.auto-approve-safe",title:"只读命令免确认",purpose:"开启后用内建规则分类器识别 POSIX known-safe 只读命令（如 `ls`、`cat`、`git status`），在 `guarded`/`auto` 策略下免确认执行；dangerous（`rm -rf`、`sudo`）与无法识别的命令默认仍需确认。工具级显式 approval override 优先；Windows PowerShell 当前全部按 unknown 处理。",defaultBehavior:`默认值为 \`${String(e.runtime.shell.autoApproveSafe)}\`。关闭后 POSIX 回归默认逐条确认；Windows PowerShell 默认逐条确认，显式 approval override 可覆盖。`,example:"runtime:\n  shell:\n    enabled: true\n    auto-approve-safe: false",setupCommand:"roll config setup shell"},{path:"runtime.shell.session.enabled",title:"Chat 会话式长命令执行",purpose:"开启后在 POSIX shell 后端注册 `roll__exec_command` + `roll__exec_poll` 工具：命令在后台会话执行、跨轮存活，模型轮询进度并读取退出码，适合超过单轮超时的长脚本。Windows 原生 session exec 暂未支持。仅交互 REPL 与 `--server` 长驻模式注册（单条消息 / `--json` 单轮会话随进程结束，不提供该工具）；`--server` 下 `exec_command` 需 `runtime.approval.overrides` 里 `roll.exec_command: auto` 显式授权。",defaultBehavior:`默认值为 \`${String(e.runtime.shell.session.enabled)}\`（关闭）。需同时开启 runtime.shell.enabled；背景会话随 roll chat 进程退出而终止。`,example:"runtime:\n  shell:\n    enabled: true\n    session:\n      enabled: true\n  approval:\n    overrides:\n      roll.exec_command: auto",setupCommand:"roll config setup shell"},{path:"skills.dirs",title:"Chat 额外 skill 目录",purpose:"`roll chat` 除自动发现项目与用户级 `.agents/skills`（`npx skills add` 的标准安装位置）及已注册 Agent 的 SKILL.md 外，额外加载的 skill 目录。目录可以直接包含 SKILL.md，也可以是多个 skill 子目录的集合。",defaultBehavior:"默认为空。标准路径 `<项目>/.agents/skills` 与 `~/.agents/skills` 始终自动发现。",example:"skills:\n  dirs:\n    - ./openclaw-roll-core-skill-template"},{path:"browser.default-instance",title:"默认浏览器实例",purpose:"多浏览器实例配置下，未显式指定 browserInstance 时使用的默认实例。",defaultBehavior:"不配置且只有一个实例时可自动推断；多个实例时工具可能返回 needs_input。",example:"browser:\n  default-instance: boss-a"},{path:"browser.instances",title:"浏览器实例声明",purpose:"声明 browser-use-agent 可使用的浏览器 profile、CDP 端口、会话目录和业务归因信息。",defaultBehavior:"不配置时 browser-use-agent 使用 legacy 单实例环境变量路径。",example:"browser:\n  instances:\n    boss-a:\n      platform: zhipin\n      mode: managed-cdp\n      cdp-port: 9222\n      user-data-dir: ~/.roll-agent/browser/boss-a"}];export function listConfigGuidanceEntries(){return CONFIG_GUIDANCE_ENTRIES}export function findConfigGuidance(e){const r=l(e.split(".")).join(".");return CONFIG_GUIDANCE_ENTRIES.find(e=>t(e.path,r))}function t(e,t){const r=l(e.split(".")).join(".");if(r===t)return!0;const a=r.split("."),n=t.split(".");return a.length===n.length&&a.every((e,l)=>e.startsWith("<")||e===n[l])}export function flattenAgentEnvDeclarations(e){return[...(e?.required??[]).map(e=>({...e,required:!0})),...(e?.optional??[]).map(e=>({...e,required:!1}))]}export function isSecretEnvName(e){return/(?:TOKEN|KEY|SECRET|PASSWORD)/iu.test(e)}

package/dist/cli/commands/config-prompts.d.ts

@@ -33,5 +33,11 @@ export interface ConfigPromptAdapter {
         readonly message: string;
         readonly initialValue?: boolean;
     }): Promise<boolean>;
+    multiselect<Value extends string>(options: {
+        readonly message: string;
+        readonly options: readonly PromptOption<Value>[];
+        readonly initialValues?: readonly Value[];
+        readonly required?: boolean;
+    }): Promise<readonly Value[]>;
 }
 export declare const clackPromptAdapter: ConfigPromptAdapter;

package/dist/cli/commands/config-prompts.js

@@ -1 +1 @@
-import{cancel as e,confirm as t,intro as a,isCancel as l,log as i,outro as u,password as o,select as r,text as n}from"@clack/prompts";const s=process.stderr;export class ConfigSetupCancelledError extends Error{constructor(){super("配置向导已取消")}}export const clackPromptAdapter={intro(e){a(e,{output:s})},outro(e){u(e,{output:s})},info(e){i.info(e,{output:s})},warn(e){i.warn(e,{output:s})},async select(e){const t=e.options.map(e=>e.hint?{value:e.value,label:e.label,hint:e.hint}:{value:e.value,label:e.label});return p(await r({message:e.message,options:t,output:s,...e.initialValue?{initialValue:e.initialValue}:{}}))},text:async e=>p(await n({message:e.message,output:s,...e.placeholder?{placeholder:e.placeholder}:{},...void 0!==e.defaultValue?{defaultValue:e.defaultValue}:{},...void 0!==e.initialValue?{initialValue:e.initialValue}:{},validate(t){const a=t??"";return e.required&&0===a.trim().length?"此项不能为空":e.validate?.(a)}})),password:async e=>p(await o({message:e.message,output:s,validate(t){const a=t??"";return e.required&&0===a.trim().length?"此项不能为空":e.validate?.(a)}})),confirm:async e=>p(await t({message:e.message,output:s,...void 0!==e.initialValue?{initialValue:e.initialValue}:{}}))};function p(t){if(l(t))throw e("已取消",{output:s}),new ConfigSetupCancelledError;return t}
+import{cancel as e,confirm as a,intro as t,isCancel as l,log as i,multiselect as u,outro as n,password as o,select as r,text as s}from"@clack/prompts";const p=process.stderr;export class ConfigSetupCancelledError extends Error{constructor(){super("配置向导已取消")}}export const clackPromptAdapter={intro(e){t(e,{output:p})},outro(e){n(e,{output:p})},info(e){i.info(e,{output:p})},warn(e){i.warn(e,{output:p})},async select(e){const a=e.options.map(e=>e.hint?{value:e.value,label:e.label,hint:e.hint}:{value:e.value,label:e.label});return c(await r({message:e.message,options:a,output:p,...e.initialValue?{initialValue:e.initialValue}:{}}))},async text(e){const a=e.placeholder??e.defaultValue;return c(await s({message:e.message,output:p,...a?{placeholder:a}:{},...void 0!==e.defaultValue?{defaultValue:e.defaultValue}:{},...void 0!==e.initialValue?{initialValue:e.initialValue}:{},validate(a){const t=a??"";if(0!==t.trim().length||void 0===e.defaultValue)return e.required&&0===t.trim().length?"此项不能为空":e.validate?.(t)}}))},password:async e=>c(await o({message:e.message,output:p,validate(a){const t=a??"";return e.required&&0===t.trim().length?"此项不能为空":e.validate?.(t)}})),confirm:async e=>c(await a({message:e.message,output:p,...void 0!==e.initialValue?{initialValue:e.initialValue}:{}})),async multiselect(e){const a=e.options.map(e=>e.hint?{value:e.value,label:e.label,hint:e.hint}:{value:e.value,label:e.label});return c(await u({message:e.message,options:a,output:p,required:e.required??!1,...e.initialValues?{initialValues:[...e.initialValues]}:{}})).map(e=>e)}};function c(a){if(l(a))throw e("已取消",{output:p}),new ConfigSetupCancelledError;return a}

package/dist/cli/commands/config-setup.d.ts

@@ -1,3 +1,8 @@
 import { type ConfigPromptAdapter } from "./config-prompts.ts";
-export type ConfigSetupModule = "llm" | "install" | "agent";
+export type ConfigSetupModule = "llm" | "install" | "agent" | "shell";
 export declare function runConfigSetup(moduleArg: string | undefined, valueArg: string | undefined, prompts?: ConfigPromptAdapter): Promise<void>;
+export declare function setupLlm(prompts: ConfigPromptAdapter): Promise<string>;
+export declare function setupInstall(prompts: ConfigPromptAdapter): Promise<string>;
+export declare function setupShell(prompts: ConfigPromptAdapter, platform?: NodeJS.Platform): Promise<string>;
+export declare function setupBash(prompts: ConfigPromptAdapter): Promise<string>;
+export declare function setupAgentEnv(agentNameArg: string | undefined, prompts: ConfigPromptAdapter): Promise<string>;

package/dist/cli/commands/config-setup.js

@@ -1 +1 @@
-import{existsSync as e,readFileSync as t,writeFileSync as r}from"node:fs";import{resolve as n}from"node:path";import{stringify as i}from"yaml";import{DEFAULT_CONFIG as a,DEFAULT_LLM_MODELS as o,DEFAULT_LLM_PROVIDER as l,LLM_PROVIDER_OPTIONS as s}from"../../config/defaults.js";import{inspectAgentEnvRequirements as c}from"../../config/helpers.js";import{loadAgentsConfig as u,parseConfigDocument as m,resolveConfigPath as f,validateConfigText as d}from"../../config/loader.js";import{encodePathToYaml as g}from"../../config/key-codec.js";import{AgentStore as p}from"../../registry/store.js";import{flattenAgentEnvDeclarations as v,isSecretEnvName as w}from"./config-guidance.js";import{ConfigSetupCancelledError as h,clackPromptAdapter as y}from"./config-prompts.js";const k=/\$\{[^}]+\}/u;export async function runConfigSetup(e,t,r=y){try{r.intro("Roll 配置向导");switch(await $(e,r)){case"llm":await b(r);break;case"install":await A(r);break;case"agent":await V(t,r)}}catch(e){if(e instanceof h)return void(process.exitCode=1);throw e}}async function $(e,t){if(void 0===e)return t.select({message:"要配置哪一类内容？",options:[{value:"llm",label:"LLM",hint:"默认模型和 provider key"},{value:"install",label:"Install network",hint:"npm registry、重试和超时"},{value:"agent",label:"Agent env",hint:"配置某个 Agent 需要的环境变量"}]});if("llm"===e||"install"===e||"agent"===e)return e;throw new Error(`未知 setup 模块: ${e}。可用: llm, install, agent`)}async function b(e){const t=await e.select({message:"选择默认 LLM provider",options:s.map(e=>({value:e,label:e,hint:o[e]})),initialValue:l}),r=await e.text({message:"默认 model",defaultValue:o[t],required:!0}),n=await e.password({message:`${t} API key（可直接输入真实 key，也可输入 \${ENV_VAR}）`,required:!0}),i=await e.text({message:"自定义 base-url（可选，留空则不写）",required:!1}),a=q();I(a.document,["llm","defaultProvider"],t),I(a.document,["llm","defaultModel"],r),I(a.document,["llm","providers",t,"apiKey"],n),i.trim().length>0?I(a.document,["llm","providers",t,"baseUrl"],i.trim()):N(a.document,["llm","providers",t,"baseUrl"]),P(a),T(e,`${t} API key`,n),e.outro(`已配置 LLM: ${t}/${r}`)}async function A(e){const t=await e.select({message:"当前安装/更新网络更接近哪种场景？",options:[{value:"default-network",label:"默认网络 / 海外网络",hint:"不设置 registry"},{value:"china-dev",label:"国内开发机",hint:"使用 https://registry.npmmirror.com"},{value:"private-registry",label:"企业内网 / 私有 registry"},{value:"advanced",label:"高级自定义"}]}),r=q();switch(t){case"default-network":j(r.document),N(r.document,["install","registry"]);break;case"china-dev":j(r.document),I(r.document,["install","registry"],"https://registry.npmmirror.com");break;case"private-registry":{const t=await e.text({message:"私有 registry URL",placeholder:"https://registry.example.com",required:!0});j(r.document),I(r.document,["install","registry"],t.trim());break}case"advanced":await x(r.document,e)}P(r),e.outro("已配置 install 网络参数")}async function x(e,t){const r=await t.text({message:"npm registry（留空则不写）",placeholder:"https://registry.npmmirror.com"}),n=await t.text({message:"fetch-retries",defaultValue:"3",required:!0,validate:D(0,10)}),i=await t.confirm({message:"是否启用 prefer-offline？",initialValue:!1}),a=await t.text({message:"network-timeout-ms",defaultValue:"120000",required:!0,validate:D(1e4,Number.MAX_SAFE_INTEGER)});I(e,["install","fetchRetries"],Number.parseInt(n,10)),I(e,["install","preferOffline"],i),I(e,["install","networkTimeoutMs"],Number.parseInt(a,10)),r.trim().length>0?I(e,["install","registry"],r.trim()):N(e,["install","registry"])}async function V(e,t){const{agentsConfig:r}=u(),n=new p(r.dataDir),i=await S(n.list(),e,t),a=c(i.skill.name,i.skill.env,r.env);if(!a)throw new Error(`Agent "${i.skill.name}" 未声明环境变量需求。`);const o=q(),l={...r.env?.[i.skill.name]??{}},s=v(i.skill.env),m=new Map(a.items.map(e=>[e.name,e]));for(const e of s.filter(e=>e.required)){const r=m.get(e.name),n=await M({declaration:e,yamlValue:l[e.name],source:r?.source,processEnvValue:process.env[e.name]},t);void 0!==n&&(l[e.name]=n)}if(await t.confirm({message:"是否配置可选环境变量？",initialValue:!1}))for(const e of s.filter(e=>!e.required)){const r=m.get(e.name),n=await M({declaration:e,yamlValue:l[e.name],source:r?.source,processEnvValue:process.env[e.name]},t);void 0!==n&&(l[e.name]=n)}I(o.document,["agents","env",i.skill.name],l),P(o);for(const[e,r]of Object.entries(l))w(e)&&T(t,e,r);Y(t,i),t.outro(`已配置 Agent 环境变量: ${i.skill.name}`)}async function S(e,t,r){if(void 0!==t){const r=e.find(e=>e.skill.name===t);if(!r)throw new Error(`Agent "${t}" 未找到`);if(!E(r))throw new Error(`Agent "${t}" 未声明环境变量需求。`);return r}const n=e.filter(E);if(0===n.length)throw new Error("没有已注册且声明环境变量需求的 Agent。");const i=await r.select({message:"选择要配置的 Agent",options:n.map(e=>({value:e.skill.name,label:e.skill.name,hint:e.skill.description}))}),a=n.find(e=>e.skill.name===i);if(!a)throw new Error(`Agent "${i}" 未找到`);return a}function E(e){return v(e.skill.env).length>0}async function M(e,t){const{declaration:r,processEnvValue:n,source:i,yamlValue:a}=e,o="agents.env"===i&&O(a),l=[r.required?"必填":"可选",o?"回车保留当前值":void 0].filter(e=>void 0!==e).join("，"),s=`${r.name}（${l}）`,c=[r.purpose?`用途: ${r.purpose}`:void 0,r.example?`示例: ${r.example}`:void 0,r.default?`默认: ${r.default}`:void 0,o?"当前 YAML 已配置，回车保留当前值。":void 0,void 0===a||o?void 0:"当前 YAML 值为空或占位符未解析，会被视为缺失。","process.env"===i?"当前来源: 当前 shell 临时环境变量，尚未持久写入 YAML。":void 0].filter(e=>void 0!==e).join("\n");if(c.length>0&&t.info(c),"process.env"===i&&"string"==typeof n&&n.length>0){if(await t.confirm({message:`是否将 ${r.name} 的当前 shell 值写入 roll.config.yaml？`,initialValue:!0}))return n}const u=r.required&&!o&&void 0===r.default&&"process.env"!==i,m={message:s,...o&&void 0!==a?{defaultValue:a}:{},...void 0!==r.example?{placeholder:r.example}:{},required:u},f=w(r.name)?await t.password({message:s,required:u}):await t.text(m);return 0===f.trim().length?o?a:void 0:f}function j(e){I(e,["install","fetchRetries"],a.install.fetchRetries),I(e,["install","preferOffline"],a.install.preferOffline),I(e,["install","networkTimeoutMs"],a.install.networkTimeoutMs)}function q(){const r=f(),i=r??n(process.cwd(),"roll.config.yaml");if(void 0===r||!e(i))return{configPath:i,existed:!1,document:L()};const a=t(i,"utf-8");return{configPath:i,existed:!0,raw:a,document:m(a,i)}}function L(){return{llm:{"default-provider":a.llm.defaultProvider,"default-model":a.llm.defaultModel,providers:{}},ask:{},agents:{"data-dir":a.agents.dataDir}}}function P(e){const t=i(e.document,{lineWidth:0});d(t,e.configPath),e.existed&&void 0!==e.raw&&r(R(e.configPath),e.raw,"utf-8"),r(e.configPath,t,"utf-8")}function R(e){const t=new Date;return`${e}.bak.${[t.getFullYear().toString().padStart(4,"0"),(t.getMonth()+1).toString().padStart(2,"0"),t.getDate().toString().padStart(2,"0"),"-",t.getHours().toString().padStart(2,"0"),t.getMinutes().toString().padStart(2,"0"),t.getSeconds().toString().padStart(2,"0")].join("")}`}function I(e,t,r){const n=g(t),i=n[n.length-1];if(void 0===i)throw new Error("配置路径不能为空");let a=e;for(const e of n.slice(0,-1)){const t=a[e];("object"!=typeof t||null===t||Array.isArray(t))&&(a[e]={}),a=a[e]}a[i]=r}function N(e,t){const r=g(t),n=r[r.length-1];if(void 0===n)return;let i=e;for(const e of r.slice(0,-1)){if("object"!=typeof i||null===i||Array.isArray(i))return;i=i[e]}"object"!=typeof i||null===i||Array.isArray(i)||delete i[n]}function D(e,t){return r=>{if(!/^\d+$/u.test(r))return"请输入整数";const n=Number.parseInt(r,10);return n<e||n>t?`请输入 ${String(e)} 到 ${String(t)} 之间的整数`:void 0}}function O(e){return"string"==typeof e&&e.length>0&&!k.test(e)}function T(e,t,r){0===r.trim().length||k.test(r)||e.warn(`${t} 将以明文写入 roll.config.yaml，建议改用 \${ENV_VAR} 引用并避免把配置文件提交到版本库。`)}function Y(e,t){const r=t.skill.name;switch(t.runtime.ownership){case"core-managed":e.info(`需重启后生效：roll agent stop ${r} && roll agent start ${r}`);break;case"external-managed":e.info(`请重启你自行管理的 "${r}" 进程以加载新环境变量。`);break;case"on-demand":e.info(`下次 roll run / roll ask 调用 "${r}" 时自动生效。`)}}
+import{existsSync as e,readFileSync as t,writeFileSync as r}from"node:fs";import{homedir as n}from"node:os";import{resolve as a}from"node:path";import{stringify as i}from"yaml";import{DEFAULT_CONFIG as o,DEFAULT_LLM_MODELS as s,DEFAULT_LLM_PROVIDER as l,LLM_PROVIDER_OPTIONS as c}from"../../config/defaults.js";import{inspectAgentEnvRequirements as u}from"../../config/helpers.js";import{loadAgentsConfig as m,parseConfigDocument as f,resolveConfigPath as d,validateConfigText as g}from"../../config/loader.js";import{encodePathToYaml as p}from"../../config/key-codec.js";import{detectKnownConfigMigrations as h,formatConfigMigrationError as v}from"../../config/migration.js";import{AgentStore as w}from"../../registry/store.js";import{flattenAgentEnvDeclarations as y,isSecretEnvName as k}from"./config-guidance.js";import{ConfigSetupCancelledError as $,clackPromptAdapter as b}from"./config-prompts.js";const A=/\$\{[^}]+\}/u;export async function runConfigSetup(e,t,r=b){try{r.intro("Roll 配置向导"),q();switch(await x(e,r)){case"llm":r.outro(await setupLlm(r));break;case"install":r.outro(await setupInstall(r));break;case"agent":r.outro(await setupAgentEnv(t,r));break;case"shell":r.outro(await setupShell(r))}}catch(e){if(e instanceof $)return void(process.exitCode=1);throw e}}async function x(e,t){if(void 0===e)return t.select({message:"要配置哪一类内容？",options:[{value:"llm",label:"LLM",hint:"默认模型和 provider key"},{value:"install",label:"Install network",hint:"npm registry、重试和超时"},{value:"agent",label:"Agent env",hint:"配置某个 Agent 需要的环境变量"},{value:"shell",label:"Chat shell 工具",hint:"roll chat 内建本机命令执行能力（默认关闭）"}]});if("llm"===e||"install"===e||"agent"===e||"shell"===e)return e;if("bash"===e)return"shell";throw new Error(`未知 setup 模块: ${e}。可用: llm, install, agent, shell`)}export async function setupLlm(e){q();const t=await e.select({message:"选择默认 LLM provider",options:c.map(e=>({value:e,label:e,hint:s[e]})),initialValue:l}),r=await e.text({message:"默认 model",defaultValue:s[t],required:!0}),n=await e.password({message:`${t} API key（可直接输入真实 key，也可输入 \${ENV_VAR}）`,required:!0}),a=await e.text({message:"自定义 base-url（可选，留空则不写）",required:!1}),i=q();return N(i.document,["llm","defaultProvider"],t),N(i.document,["llm","defaultModel"],r),N(i.document,["llm","providers",t,"apiKey"],n),a.trim().length>0?N(i.document,["llm","providers",t,"baseUrl"],a.trim()):O(i.document,["llm","providers",t,"baseUrl"]),R(i),D(e,`${t} API key`,n),`已配置 LLM: ${t}/${r}（写入 ${i.configPath}）`}export async function setupInstall(e){q();const t=await e.select({message:"当前安装/更新网络更接近哪种场景？",options:[{value:"default-network",label:"默认网络 / 海外网络",hint:"不设置 registry"},{value:"china-dev",label:"国内开发机",hint:"使用 https://registry.npmmirror.com"},{value:"private-registry",label:"企业内网 / 私有 registry"},{value:"advanced",label:"高级自定义"}]}),r=await S(t,e),n=q();switch(r.scenario){case"default-network":P(n.document),O(n.document,["install","registry"]);break;case"china-dev":P(n.document),N(n.document,["install","registry"],"https://registry.npmmirror.com");break;case"private-registry":P(n.document),N(n.document,["install","registry"],r.registry);break;case"advanced":{const{registry:e,fetchRetries:t,preferOffline:a,networkTimeoutMs:i}=r.values;N(n.document,["install","fetchRetries"],t),N(n.document,["install","preferOffline"],a),N(n.document,["install","networkTimeoutMs"],i),e.length>0?N(n.document,["install","registry"],e):O(n.document,["install","registry"]);break}}return R(n),`已配置 install 网络参数（写入 ${n.configPath}）`}export async function setupShell(e,t=process.platform){q();const r=await e.confirm({message:"启用 roll chat 内建 shell 工具（允许模型在本机执行命令；默认确认策略受 runtime.approval 及显式 override 控制）？",initialValue:!1});let n=!0,a=!1;const i="win32"===t;r&&i&&e.warn("Windows 原生 shell 当前仅支持 PowerShell 7 one-shot；安全命令自动放行和 session exec 暂不生效。默认每条命令都需确认；显式 approval override（roll.powershell: auto）可覆盖此默认策略。"),r&&!i&&(n=await e.confirm({message:"安全只读命令（ls/grep 等）自动放行，无需逐条确认？",initialValue:!0}),a=await e.confirm({message:"启用长跑命令会话（session exec，供 dev server 等常驻进程使用）？",initialValue:!1}));const o=q();N(o.document,["runtime","shell","enabled"],r),r&&!i&&(N(o.document,["runtime","shell","autoApproveSafe"],n),N(o.document,["runtime","shell","session","enabled"],a)),R(o);return`已${r?"启用":"禁用"} chat shell 工具${r&&i?"；Windows 当前仅启用 PowerShell one-shot，默认逐条确认（显式 approval override 可覆盖）":""}（写入 ${o.configPath}）`}export async function setupBash(e){return setupShell(e)}async function S(e,t){switch(e){case"default-network":case"china-dev":return{scenario:e};case"private-registry":return{scenario:e,registry:(await t.text({message:"私有 registry URL",placeholder:"https://registry.example.com",required:!0})).trim()};case"advanced":return{scenario:e,values:await V(t)}}}async function V(e){const t=await e.text({message:"npm registry（留空则不写）",placeholder:"https://registry.npmmirror.com"}),r=await e.text({message:"fetch-retries",defaultValue:"3",required:!0,validate:T(0,10)}),n=await e.confirm({message:"是否启用 prefer-offline？",initialValue:!1}),a=await e.text({message:"network-timeout-ms",defaultValue:"120000",required:!0,validate:T(1e4,Number.MAX_SAFE_INTEGER)});return{registry:t.trim(),fetchRetries:Number.parseInt(r,10),preferOffline:n,networkTimeoutMs:Number.parseInt(a,10)}}export async function setupAgentEnv(e,t){q();const{agentsConfig:r}=m(),n=new w(r.dataDir),a=await E(n.list(),e,t),i=u(a.skill.name,a.skill.env,r.env);if(!i)throw new Error(`Agent "${a.skill.name}" 未声明环境变量需求。`);const o={...r.env?.[a.skill.name]??{}},s=y(a.skill.env),l=new Map(i.items.map(e=>[e.name,e]));for(const e of s.filter(e=>e.required)){const r=l.get(e.name),n=await j({declaration:e,yamlValue:o[e.name],source:r?.source,processEnvValue:process.env[e.name]},t);void 0!==n&&(o[e.name]=n)}if(await t.confirm({message:"是否配置可选环境变量？",initialValue:!1}))for(const e of s.filter(e=>!e.required)){const r=l.get(e.name),n=await j({declaration:e,yamlValue:o[e.name],source:r?.source,processEnvValue:process.env[e.name]},t);void 0!==n&&(o[e.name]=n)}const c=q();N(c.document,["agents","env",a.skill.name],o),R(c);for(const[e,r]of Object.entries(o))k(e)&&D(t,e,r);return Y(t,a),`已配置 Agent 环境变量: ${a.skill.name}（写入 ${c.configPath}）`}async function E(e,t,r){if(void 0!==t){const r=e.find(e=>e.skill.name===t);if(!r)throw new Error(`Agent "${t}" 未找到`);if(!M(r))throw new Error(`Agent "${t}" 未声明环境变量需求。`);return r}const n=e.filter(M);if(0===n.length)throw new Error("没有已注册且声明环境变量需求的 Agent。");const a=await r.select({message:"选择要配置的 Agent",options:n.map(e=>({value:e.skill.name,label:e.skill.name,hint:e.skill.description}))}),i=n.find(e=>e.skill.name===a);if(!i)throw new Error(`Agent "${a}" 未找到`);return i}function M(e){return y(e.skill.env).length>0}async function j(e,t){const{declaration:r,processEnvValue:n,source:a,yamlValue:i}=e,o="agents.env"===a&&C(i),s=[r.required?"必填":"可选",o?"回车保留当前值":void 0].filter(e=>void 0!==e).join("，"),l=`${r.name}（${s}）`,c=[r.purpose?`用途: ${r.purpose}`:void 0,r.example?`示例: ${r.example}`:void 0,r.default?`默认: ${r.default}`:void 0,o?"当前 YAML 已配置，回车保留当前值。":void 0,void 0===i||o?void 0:"当前 YAML 值为空或占位符未解析，会被视为缺失。","process.env"===a?"当前来源: 当前 shell 临时环境变量，尚未持久写入 YAML。":void 0].filter(e=>void 0!==e).join("\n");if(c.length>0&&t.info(c),"process.env"===a&&"string"==typeof n&&n.length>0){if(await t.confirm({message:`是否将 ${r.name} 的当前 shell 值写入 roll.config.yaml？`,initialValue:!0}))return n}const u=r.required&&!o&&void 0===r.default&&"process.env"!==a,m={message:l,...o&&void 0!==i?{defaultValue:i}:{},...void 0!==r.example?{placeholder:r.example}:{},required:u},f=k(r.name)?await t.password({message:l,required:u}):await t.text(m);return 0===f.trim().length?o?i:void 0:f}function P(e){N(e,["install","fetchRetries"],o.install.fetchRetries),N(e,["install","preferOffline"],o.install.preferOffline),N(e,["install","networkTimeoutMs"],o.install.networkTimeoutMs)}function q(){const r=d(),i=r??a(n(),"roll.config.yaml");if(void 0===r||!e(i))return{configPath:i,existed:!1,document:L()};const o=t(i,"utf-8"),s=f(o,i),l=h(s);if(l.needsMigration)throw new Error(v(i,l));return{configPath:i,existed:!0,raw:o,document:s}}function L(){return{llm:{"default-provider":o.llm.defaultProvider,"default-model":o.llm.defaultModel,providers:{}},ask:{},agents:{"data-dir":o.agents.dataDir}}}function R(e){const t=i(e.document,{lineWidth:0});g(t,e.configPath),e.existed&&void 0!==e.raw&&r(I(e.configPath),e.raw,"utf-8"),r(e.configPath,t,"utf-8")}function I(e){const t=new Date;return`${e}.bak.${[t.getFullYear().toString().padStart(4,"0"),(t.getMonth()+1).toString().padStart(2,"0"),t.getDate().toString().padStart(2,"0"),"-",t.getHours().toString().padStart(2,"0"),t.getMinutes().toString().padStart(2,"0"),t.getSeconds().toString().padStart(2,"0")].join("")}`}function N(e,t,r){const n=p(t),a=n[n.length-1];if(void 0===a)throw new Error("配置路径不能为空");let i=e;for(const e of n.slice(0,-1)){const t=i[e];("object"!=typeof t||null===t||Array.isArray(t))&&(i[e]={}),i=i[e]}i[a]=r}function O(e,t){const r=p(t),n=r[r.length-1];if(void 0===n)return;let a=e;for(const e of r.slice(0,-1)){if("object"!=typeof a||null===a||Array.isArray(a))return;a=a[e]}"object"!=typeof a||null===a||Array.isArray(a)||delete a[n]}function T(e,t){return r=>{if(!/^\d+$/u.test(r))return"请输入整数";const n=Number.parseInt(r,10);return n<e||n>t?`请输入 ${String(e)} 到 ${String(t)} 之间的整数`:void 0}}function C(e){return"string"==typeof e&&e.length>0&&!A.test(e)}function D(e,t,r){0===r.trim().length||A.test(r)||e.warn(`${t} 将以明文写入 roll.config.yaml，建议改用 \${ENV_VAR} 引用并避免把配置文件提交到版本库。`)}function Y(e,t){const r=t.skill.name;switch(t.runtime.ownership){case"core-managed":e.info(`需重启后生效：roll agent stop ${r} && roll agent start ${r}`);break;case"external-managed":e.info(`请重启你自行管理的 "${r}" 进程以加载新环境变量。`);break;case"on-demand":e.info(`下次 roll run / roll ask 调用 "${r}" 时自动生效。`)}}

package/dist/cli/commands/config.d.ts

@@ -16,3 +16,4 @@ declare const _default: import("citty").CommandDef<{
     };
 }>;
 export default _default;
+export declare function migrateConfig(): void;

package/dist/cli/commands/config.js

@@ -1 +1 @@
-import{defineCommand as o}from"citty";import{readFileSync as e,writeFileSync as t,existsSync as r}from"node:fs";import{resolve as n}from"node:path";import{createInterface as i}from"node:readline/promises";import{stringify as s}from"yaml";import{DEFAULT_CONFIG as c,DEFAULT_LLM_MODELS as l,LLM_PROVIDER_OPTIONS as a}from"../../config/defaults.js";import{inspectConfigFile as f,loadConfig as d,parseConfigDocument as u,validateConfigText as p}from"../../config/loader.js";import{encodePathToYaml as g,normalizeUserPath as m}from"../../config/key-codec.js";import{applyKnownConfigMigrations as v}from"../../config/migration.js";import{explainConfig as y}from"./config-explain.js";import{runConfigSetup as h}from"./config-setup.js";export default o({meta:{description:"管理全局配置"},args:{action:{type:"positional",description:"操作（init/get/set/migrate/setup/explain）",required:!0},key:{type:"positional",description:"配置键（get/set 时使用，用英文句点 `.` 分隔，如 ask.confirm-threshold）",required:!1},value:{type:"positional",description:"配置值（set 时使用）",required:!1}},async run({args:o}){try{if("init"===o.action)return void await j();if("get"===o.action)return void K(o.key);if("set"===o.action)return void q(o.key,o.value);if("migrate"===o.action)return void A();if("setup"===o.action)return process.stdin.isTTY?void await h(o.key,o.value):(console.error("✗ `roll config setup` 需要交互式终端。"),console.error("  非交互环境请改用 `roll config set <key> <value>` 或直接编辑 roll.config.yaml。"),console.error("  查看配置说明：`roll config explain <key>`。"),void(process.exitCode=1));if("explain"===o.action)return void y(o.key);console.error(`✗ 未知操作: ${o.action}。可用: init, get, set, migrate, setup, explain`),process.exitCode=1}catch(o){const e=o instanceof Error?o.message:String(o);console.error(`✗ ${e}`),process.exitCode=1}}});const $={anthropic:"ANTHROPIC_API_KEY",openai:"OPENAI_API_KEY",qwen:"DASHSCOPE_API_KEY",deepseek:"DEEPSEEK_API_KEY"};function P(o,e){const t=o?.trim();return t||e}function w(o){return a.some(e=>e===o)}function S(o){return w(o)?l[o]:c.llm.defaultModel}function k(o){return w(o)?$[o]:$.anthropic}function E({provider:o,model:e,apiKeyEnv:t}){return`llm:\n  default-provider: ${o}\n  default-model: ${e}\n  providers:\n    ${o}:\n      api-key: \${${t}}\n\nask:\n  confirm-threshold: 0.5\n\nagents:\n  data-dir: ~/.roll-agent/agents\n`}async function x(){if(!process.stdin.isTTY){const[o,t,r]=e(0,"utf-8").split(/\r?\n/u),n=P(o,c.llm.defaultProvider);return{provider:n,model:P(t,S(n)),apiKeyEnv:P(r,k(n))}}const o=i({input:process.stdin,output:process.stderr}),t=P(await o.question(`默认 LLM provider (${a.join("/")}) [${c.llm.defaultProvider}]: `),c.llm.defaultProvider),r=S(t),n=P(await o.question(`默认 model [${r}]: `),r),s=k(t),l=P(await o.question(`API Key 环境变量名 [${s}]: `),s);return o.close(),{provider:t,model:n,apiKeyEnv:l}}async function j(){const o=n(process.cwd(),"roll.config.yaml");if(r(o)){const e=f({configPath:o});switch(e.status){case"needs-migration":console.error(`⚠ 现有配置文件需要迁移: ${o}`),console.error("  建议先运行 `roll config migrate`，再决定是否重新初始化。");break;case"invalid":console.error(`⚠ 现有配置文件存在问题:\n${e.error.message}`)}if(console.error(`⚠ 配置文件已存在: ${o}`),!process.stdin.isTTY)throw new Error("非交互模式下不会覆盖现有配置文件，请手动删除后重试。");const t=i({input:process.stdin,output:process.stderr}),r=await t.question("是否覆盖？(y/N) ");if(t.close(),"y"!==r.toLowerCase())return void console.error("已取消。")}const e=E(await x());p(e,o),t(o,e,"utf-8"),console.log(`✓ 配置文件已创建: ${o}`)}function C(o){const e=new Date;return`${o}.bak.${[e.getFullYear().toString().padStart(4,"0"),(e.getMonth()+1).toString().padStart(2,"0"),e.getDate().toString().padStart(2,"0"),"-",e.getHours().toString().padStart(2,"0"),e.getMinutes().toString().padStart(2,"0"),e.getSeconds().toString().padStart(2,"0")].join("")}`}function A(){const o=f();if("not-found"===o.status)throw new Error("未找到配置文件。请先运行 roll config init");if("valid"===o.status)return void console.log(`✓ 配置文件已是最新格式，无需迁移: ${o.configPath}`);if("invalid"===o.status)throw o.error;const e=u(o.raw,o.configPath),r=v(e);if(!r.ok){const o=r.issues.map(o=>`  - ${o.message}`).join("\n");throw new Error(`配置无法自动迁移:\n${o}`)}if(!r.changed)return void console.log(`✓ 配置文件已是最新格式，无需迁移: ${o.configPath}`);const n=C(o.configPath);t(n,o.raw,"utf-8");const i=s(r.document,{lineWidth:0});p(i,o.configPath),t(o.configPath,i,"utf-8"),console.log(`✓ 配置文件已迁移: ${o.configPath}`),console.log(`✓ 已备份原文件: ${n}`);for(const o of r.summary)console.log(`  - ${o}`)}function K(o){const{config:e,configPath:t}=d();if(!o)return console.log(JSON.stringify(e,null,2)),void(t&&console.error(`(来源: ${t})`));const r=m(o.split("."));let n=e;for(const e of r){if("object"!=typeof n||null===n)return console.error(`✗ 配置键 "${o}" 不存在`),void(process.exitCode=1);n=n[e]}if(void 0===n)return console.error(`✗ 配置键 "${o}" 不存在`),void(process.exitCode=1);console.log("object"==typeof n?JSON.stringify(n,null,2):String(n))}function q(o,r){if(!o||void 0===r)return console.error("✗ 用法: roll config set <key> <value>"),console.error("  示例: roll config set ask.confirm-threshold 0.5"),void(process.exitCode=1);const{configPath:n}=d();if(!n)return console.error("✗ 未找到配置文件。请先运行 roll config init"),void(process.exitCode=1);const i=e(n,"utf-8"),c=u(i,n),l=g(o.split(".")),a=l[l.length-1];if(void 0===a)return console.error("✗ 配置键不能为空"),void(process.exitCode=1);let f=c;for(let o=0;o<l.length-1;o++){const e=l[o],t=f[e];("object"!=typeof t||null===t||Array.isArray(t))&&(f[e]={}),f=f[e]}let m=r;"true"===r?m=!0:"false"===r?m=!1:/^\d+(\.\d+)?$/.test(r)&&(m=Number(r)),f[a]=m;const v=s(c,{lineWidth:0});p(v,n),t(n,v,"utf-8"),console.log(`✓ ${o} = ${String(m)}`),console.error(`  (已写入: ${n})`)}
+import{defineCommand as o}from"citty";import{readFileSync as t,writeFileSync as e,existsSync as r}from"node:fs";import{homedir as n}from"node:os";import{resolve as i}from"node:path";import{createInterface as s}from"node:readline/promises";import{stringify as c}from"yaml";import{DEFAULT_CONFIG as l,DEFAULT_LLM_MODELS as a,LLM_PROVIDER_OPTIONS as f}from"../../config/defaults.js";import{inspectConfigFile as d,loadConfig as u,parseConfigDocument as p,resolveConfigPath as g,validateConfigText as m}from"../../config/loader.js";import{encodePathToYaml as v,normalizeUserPath as y}from"../../config/key-codec.js";import{applyKnownConfigMigrations as h}from"../../config/migration.js";import{explainConfig as $}from"./config-explain.js";import{runConfigSetup as P}from"./config-setup.js";export default o({meta:{description:"管理全局配置"},args:{action:{type:"positional",description:"操作（init/get/set/migrate/setup/explain）",required:!0},key:{type:"positional",description:"配置键（get/set 时使用，用英文句点 `.` 分隔，如 ask.confirm-threshold）",required:!1},value:{type:"positional",description:"配置值（set 时使用）",required:!1}},async run({args:o}){try{if("init"===o.action)return void await A();if("get"===o.action)return void q(o.key);if("set"===o.action)return void Y(o.key,o.value);if("migrate"===o.action)return void migrateConfig();if("setup"===o.action)return process.stdin.isTTY?void await P(o.key,o.value):(console.error("✗ `roll config setup` 需要交互式终端。"),console.error("  非交互环境请改用 `roll config set <key> <value>` 或直接编辑 roll.config.yaml。"),console.error("  查看配置说明：`roll config explain <key>`。"),void(process.exitCode=1));if("explain"===o.action)return void $(o.key);console.error(`✗ 未知操作: ${o.action}。可用: init, get, set, migrate, setup, explain`),process.exitCode=1}catch(o){const t=o instanceof Error?o.message:String(o);console.error(`✗ ${t}`),process.exitCode=1}}});const S={anthropic:"ANTHROPIC_API_KEY",openai:"OPENAI_API_KEY",qwen:"DASHSCOPE_API_KEY",deepseek:"DEEPSEEK_API_KEY"};function w(o,t){const e=o?.trim();return e||t}function k(o){return f.some(t=>t===o)}function E(o){return k(o)?a[o]:l.llm.defaultModel}function x(o){return k(o)?S[o]:S.anthropic}function C({provider:o,model:t,apiKeyEnv:e}){return`llm:\n  default-provider: ${o}\n  default-model: ${t}\n  providers:\n    ${o}:\n      api-key: \${${e}}\n\nask:\n  confirm-threshold: 0.5\n\nagents:\n  data-dir: ~/.roll-agent/agents\n`}async function j(){if(!process.stdin.isTTY){const[o,e,r]=t(0,"utf-8").split(/\r?\n/u),n=w(o,l.llm.defaultProvider);return{provider:n,model:w(e,E(n)),apiKeyEnv:w(r,x(n))}}const o=s({input:process.stdin,output:process.stderr}),e=w(await o.question(`默认 LLM provider (${f.join("/")}) [${l.llm.defaultProvider}]: `),l.llm.defaultProvider),r=E(e),n=w(await o.question(`默认 model [${r}]: `),r),i=x(e),c=w(await o.question(`API Key 环境变量名 [${i}]: `),i);return o.close(),{provider:e,model:n,apiKeyEnv:c}}async function A(){const o=g()??i(n(),"roll.config.yaml");if(r(o)){const t=d({configPath:o});switch(t.status){case"needs-migration":console.error(`⚠ 现有配置文件需要迁移: ${o}`),console.error("  建议先运行 `roll config migrate`，再决定是否重新初始化。");break;case"invalid":console.error(`⚠ 现有配置文件存在问题:\n${t.error.message}`)}if(console.error(`⚠ 配置文件已存在: ${o}`),!process.stdin.isTTY)throw new Error("非交互模式下不会覆盖现有配置文件，请手动删除后重试。");const e=s({input:process.stdin,output:process.stderr}),r=await e.question("是否覆盖？(y/N) ");if(e.close(),"y"!==r.toLowerCase())return void console.error("已取消。")}const t=C(await j());m(t,o),e(o,t,"utf-8"),console.log(`✓ 配置文件已创建: ${o}`)}function K(o){const t=new Date;return`${o}.bak.${[t.getFullYear().toString().padStart(4,"0"),(t.getMonth()+1).toString().padStart(2,"0"),t.getDate().toString().padStart(2,"0"),"-",t.getHours().toString().padStart(2,"0"),t.getMinutes().toString().padStart(2,"0"),t.getSeconds().toString().padStart(2,"0")].join("")}`}export function migrateConfig(){const o=d();if("not-found"===o.status)throw new Error("未找到配置文件。请先运行 roll config init");if("valid"===o.status)return void console.log(`✓ 配置文件已是最新格式，无需迁移: ${o.configPath}`);if("invalid"===o.status)throw o.error;const t=p(o.raw,o.configPath),r=h(t);if(!r.ok){const o=r.issues.map(o=>`  - ${o.message}`).join("\n");throw new Error(`配置无法自动迁移:\n${o}`)}if(!r.changed)return void console.log(`✓ 配置文件已是最新格式，无需迁移: ${o.configPath}`);const n=c(r.document,{lineWidth:0});m(n,o.configPath);const i=K(o.configPath);e(i,o.raw,"utf-8"),e(o.configPath,n,"utf-8"),console.log(`✓ 配置文件已迁移: ${o.configPath}`),console.log(`✓ 已备份原文件: ${i}`);for(const o of r.summary)console.log(`  - ${o}`)}function q(o){const{config:t,configPath:e}=u();if(!o)return console.log(JSON.stringify(t,null,2)),void(e&&console.error(`(来源: ${e})`));const r=y(o.split("."));let n=t;for(const t of r){if("object"!=typeof n||null===n)return console.error(`✗ 配置键 "${o}" 不存在`),void(process.exitCode=1);n=n[t]}if(void 0===n)return console.error(`✗ 配置键 "${o}" 不存在`),void(process.exitCode=1);console.log("object"==typeof n?JSON.stringify(n,null,2):String(n))}function Y(o,r){if(!o||void 0===r)return console.error("✗ 用法: roll config set <key> <value>"),console.error("  示例: roll config set ask.confirm-threshold 0.5"),void(process.exitCode=1);const{configPath:n}=u();if(!n)return console.error("✗ 未找到配置文件。请先运行 roll config init"),void(process.exitCode=1);const i=t(n,"utf-8"),s=p(i,n),l=v(o.split(".")),a=l[l.length-1];if(void 0===a)return console.error("✗ 配置键不能为空"),void(process.exitCode=1);let f=s;for(let o=0;o<l.length-1;o++){const t=l[o],e=f[t];("object"!=typeof e||null===e||Array.isArray(e))&&(f[t]={}),f=f[t]}let d=r;"true"===r?d=!0:"false"===r?d=!1:/^\d+(\.\d+)?$/.test(r)&&(d=Number(r)),f[a]=d;const g=c(s,{lineWidth:0});m(g,n),e(n,g,"utf-8"),console.log(`✓ ${o} = ${String(d)}`),console.error(`  (已写入: ${n})`)}

package/dist/cli/commands/setup.d.ts

@@ -0,0 +1,38 @@
+import { resolveAgentCatalog } from "../../registry/catalog-discovery.ts";
+import { installAgent } from "../../registry/install.ts";
+import { inspectCatalogAvailability } from "../utils/catalog-status.ts";
+import { setupAgentEnv, setupInstall, setupLlm, setupShell } from "./config-setup.ts";
+import type { ConfigPromptAdapter } from "./config-prompts.ts";
+import type { RegisteredAgent } from "../../types/agent.ts";
+import type { RollConfig } from "../../config/schema.ts";
+export interface LlmConfigStatus {
+    readonly configured: boolean;
+    readonly summary: string;
+}
+export interface RunChatOnboardingOptions {
+    readonly provider?: string;
+    readonly model?: string;
+}
+export interface SetupAgentContext {
+    readonly agentsConfig: RollConfig["agents"];
+    readonly installConfig?: RollConfig["install"];
+    readonly installConfigError?: string;
+    readonly agents: readonly RegisteredAgent[];
+}
+export interface RunSetupDeps {
+    readonly prompts?: ConfigPromptAdapter;
+    readonly detectLlm?: () => LlmConfigStatus;
+    readonly setupLlmFn?: typeof setupLlm;
+    readonly setupInstallFn?: typeof setupInstall;
+    readonly setupShellFn?: typeof setupShell;
+    readonly setupAgentEnvFn?: typeof setupAgentEnv;
+    readonly loadAgentContext?: () => SetupAgentContext;
+    readonly resolveCatalog?: typeof resolveAgentCatalog;
+    readonly inspectAvailability?: typeof inspectCatalogAvailability;
+    readonly install?: typeof installAgent;
+    readonly runDoctor?: () => Promise<void>;
+}
+export declare function runSetup(deps?: RunSetupDeps): Promise<void>;
+export declare function runChatOnboarding(deps?: RunSetupDeps, options?: RunChatOnboardingOptions): Promise<boolean>;
+declare const _default: import("citty").CommandDef<{}>;
+export default _default;

package/dist/cli/commands/setup.js

@@ -0,0 +1 @@
+var t=this&&this.__rewriteRelativeImportExtension||function(t,e){return"string"==typeof t&&/^\.\.?\//.test(t)?t.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i,function(t,n,r,i,o){return n?e?".jsx":".js":!r||i&&o?r+i+"."+o.toLowerCase()+"js":t}):t};import{defineCommand as e}from"citty";import{getAgentEnv as n,inspectLlmConfigReadiness as r}from"../../config/helpers.js";import{loadAgentsConfig as i,loadConfig as o,loadInstallConfig as a}from"../../config/loader.js";import{catalogPackageSpec as s}from"../../registry/catalog.js";import{resolveAgentCatalog as l}from"../../registry/catalog-discovery.js";import{installAgent as c}from"../../registry/install.js";import{AgentStore as g}from"../../registry/store.js";import{inspectCatalogAvailability as m}from"../utils/catalog-status.js";import{log as u}from"../utils/output.js";import{setupAgentEnv as f,setupInstall as p,setupLlm as d,setupShell as y}from"./config-setup.js";import{ConfigSetupCancelledError as w,clackPromptAdapter as h}from"./config-prompts.js";const v=import.meta.url.endsWith(".ts")?"ts":"js";export async function runSetup(t={}){const e=t.prompts??h,n=t.detectLlm??$,r=t.setupLlmFn??d,i=t.setupInstallFn??p,o=t.setupShellFn??y,a=t.setupAgentEnvFn??f,s=t.runDoctor??x;try{e.intro("Roll 一键初始化");const l=n();if(l.configured){await e.confirm({message:`已检测到 LLM 配置（${l.summary}），是否重新配置？`,initialValue:!1})&&e.info(await r(e))}else e.info(await r(e));await e.confirm({message:"是否配置安装网络（npm registry / 重试 / 超时）？",initialValue:!1})&&e.info(await i(e));await e.confirm({message:"是否配置 chat 内建 shell 工具（默认关闭）？",initialValue:!1})&&e.info(await o(e));const c=await C(e,t);for(const t of c){if(!t.envReport||0===t.envReport.missingRequired.length)continue;await e.confirm({message:`Agent "${t.agent.skill.name}" 缺少必填环境变量，现在配置？`,initialValue:!0})&&e.info(await a(t.agent.skill.name,e)),t.started||"core-managed"!==t.agent.runtime.ownership||e.info(`运行 roll agent start ${t.agent.skill.name} 启动该 Agent。`)}e.info("运行 roll doctor 检查..."),await s(),e.outro("初始化完成。下一步：`roll chat` 开始对话，或 `roll agent list` 查看已注册 Agent。")}catch(t){if(t instanceof w)return void(process.exitCode=1);throw t}}export async function runChatOnboarding(t={},e={}){const n=t.prompts??h,r=t.detectLlm??(()=>$(e)),i=t.setupLlmFn??d;try{n.intro("Roll chat 初始化");if(!await n.confirm({message:"LLM 尚未配置完成（缺少 provider 或 apiKey），现在进入初始化向导吗？",initialValue:!0}))return n.outro("已跳过初始化。"),!1;r().configured||n.info(await i(n));const e=await C(n,t);for(const t of e)t.envReport&&0!==t.envReport.missingRequired.length&&n.warn(`Agent "${t.agent.skill.name}" 缺少必填环境变量，可运行 roll config setup agent ${t.agent.skill.name} 配置。`);return n.outro("初始化完成，继续进入对话。完整初始化可运行 roll setup，环境检查可运行 roll doctor。"),!0}catch(t){if(t instanceof w)return!1;throw t}}async function C(t,e){const r=e.loadAgentContext??A,i=e.resolveCatalog??l,a=e.inspectAvailability??m,g=e.install??c,u=r();if(!u.installConfig)return t.warn(`install 配置无效，跳过官方 Agent 安装：${u.installConfigError??"未知原因"}`),[];const f=u.installConfig,p=await i(void 0,{...f.registry?{registry:f.registry}:{}}),d=await a(p,u.agents,{...f.registry?{registry:f.registry}:{}});if(0===d.length)return[];const y=await t.multiselect({message:"选择要安装的官方 Agent（空格勾选，回车确认，可全部跳过）",options:d.map(t=>({value:t.entry.shortName,label:t.entry.shortName,hint:j(t)})),initialValues:d.filter(t=>"not-installed"===t.state).map(t=>t.entry.shortName),required:!1}),w=[];for(const e of y){const r=d.find(t=>t.entry.shortName===e);if(!r)continue;const i=await g({packageSpec:s(r.entry),expectedSkillName:r.entry.skillName,replaceExisting:"installed-other-source"===r.state},{agentsConfig:u.agentsConfig,installConfig:f,getStartEnv:t=>n(o().config,t),report:e=>L(t,e)});i.ok?(t.info(`Agent "${i.agent.skill.name}" 安装并注册成功`),w.push(i)):k(t,i)}return w}function $(t={}){try{const{config:e}=o(),n=r(e,t);return{configured:n.configured,summary:n.summary}}catch{return{configured:!1,summary:""}}}function A(){const{agentsConfig:t}=i(),e=new g(t.dataDir);try{return{agentsConfig:t,installConfig:a().installConfig,agents:e.list()}}catch(n){return{agentsConfig:t,installConfigError:n instanceof Error?n.message:String(n),agents:e.list()}}}function j(t){const e="installed-package"===t.installedAgent?.source?.type?t.installedAgent.source.installedVersion:void 0,n={"not-installed":()=>t.latestVersion?`最新 v${t.latestVersion}`:"未安装",installed:()=>"update-available"===t.update?.status&&t.latestVersion?`已安装${e?` v${e}`:""}，可更新到 v${t.latestVersion}`:"已安装"+(e?` v${e}`:""),"installed-other-source":()=>"已通过其他来源注册，选择将替换为 npm 安装"};return`${t.entry.description}（${n[t.state]()}）`}function L(t,e){"retry"!==e.type?"warn"!==e.type?t.info(e.message):t.warn(e.message):t.warn(`安装遇到网络问题，${Math.round(e.delayMs/1e3)}s 后重试（第 ${e.attempt+1} 次）...`)}function k(t,e){if("setup"===e.step)return t.warn(`Agent setup 失败：${e.message}`),void(e.retryCommand&&t.info(`重试命令: ${e.retryCommand}`));t.warn(e.message)}async function x(){const e=new URL(`./doctor.${v}`,import.meta.url).href,n=(await import(t(e))).default,{runCommand:r}=await import("citty");await r(n,{rawArgs:[]})}export default e({meta:{description:"一键初始化：配置 LLM、安装官方 Agent、检查环境（新设备 onboarding）"},args:{},async run(){if(!process.stdin.isTTY||!process.stderr.isTTY)return u.error("roll setup 需要交互式终端。非交互环境请使用 roll config set 与 roll agent install。"),void(process.exitCode=1);await runSetup()}});

package/dist/cli/commands/skills-install.d.ts

@@ -0,0 +1,30 @@
+declare const _default: import("citty").CommandDef<{
+    source: {
+        type: "positional";
+        description: string;
+        required: true;
+    };
+    target: {
+        type: "string";
+        description: string;
+    };
+    project: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+    dir: {
+        type: "string";
+        description: string;
+    };
+    skill: {
+        type: "string";
+        description: string;
+    };
+    json: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+}>;
+export default _default;

package/dist/cli/commands/skills-install.js

@@ -0,0 +1 @@
+import{defineCommand as t}from"citty";import{resolve as r}from"node:path";import{expandTilde as i,loadAgentsConfig as e}from"../../config/loader.js";import{collectInstallableSkills as o,findExistingSkillInstalls as s,installSkillsToDir as l}from"../../skills/install.js";import{ORCHESTRATOR_SKILL_TARGETS as n,detectOrchestratorTargets as a,isOrchestratorTargetId as c}from"../../skills/orchestrators.js";import{cloneOrPullRepo as p,isGitUrl as d,repoNameFromUrl as f}from"../utils/git-source.js";import{log as u}from"../utils/output.js";import{ConfigSetupCancelledError as g,clackPromptAdapter as m}from"./config-prompts.js";export default t({meta:{description:"安装 skill 到 orchestrator 的 skills 目录（Claude Code / Codex / 通用 .agents）"},args:{source:{type:"positional",description:"skill 来源：包含 SKILL.md 的本地目录（或多 skill 子目录集合）、Git 仓库 URL",required:!0},target:{type:"string",description:`目标 orchestrator，逗号分隔或 all（${n.map(t=>`${t.id}=${t.userDir}`).join("、")}；agents 目录同时被 roll chat 读取）`},project:{type:"boolean",description:"安装到当前项目目录（如 .claude/skills）而非用户级目录",default:!1},dir:{type:"string",description:"自定义目标目录（与 --target 互斥）"},skill:{type:"string",description:"只安装指定名称的 skill，逗号分隔（默认安装来源中的全部 skill）"},json:{type:"boolean",description:"JSON 格式输出安装结果",default:!1}},async run({args:t}){if(t.dir&&(t.target||t.project))return u.error("--dir 与 --target / --project 互斥，请只指定一种目标方式"),void(process.exitCode=1);let n;if(d(t.source)){const{agentsConfig:i}=e(),o=r(i.dataDir,"skill-repos",f(t.source));try{const{action:r}=await p(t.source,o);u.info("cloned"===r?`已克隆到 ${o}`:`已更新 ${o}`)}catch(t){return u.error(`拉取 skill 仓库失败: ${t instanceof Error?t.message:String(t)}`),void(process.exitCode=1)}n=o}else n=r(i(t.source));const a=o(n);for(const t of a.issues)u.warn(t);const c=k(a.skills,t.skill);if(!c)return void(process.exitCode=1);if(0===c.length)return u.error(`未在 ${n} 找到可安装的 skill`),void(process.exitCode=1);let m;try{const r=await h(t);if(!r)return void(process.exitCode=1);m=r}catch(t){if(t instanceof g)return void(process.exitCode=1);throw t}const j=[];for(const{id:t,dir:r}of m){const i=s(c,r);i.length>0&&u.warn(`将覆盖 ${r} 中已有的 skill（手工修改会丢失）: ${i.join(", ")}`);const e=l(c,r);j.push({target:t,dir:r,skills:e});for(const t of e)u.success(`${t.overwritten?"已更新":"已安装"} ${t.name} → ${t.targetPath}`)}t.json&&console.log(JSON.stringify(j,null,2))}});function k(t,r){if(!r)return t;const i=r.split(",").map(t=>t.trim()).filter(t=>t.length>0),e=new Map(t.map(t=>[t.name,t])),o=i.filter(t=>!e.has(t));if(!(o.length>0))return i.map(t=>e.get(t)).filter(t=>void 0!==t);u.error(`来源中不存在这些 skill: ${o.join(", ")}（可用: ${t.map(t=>t.name).join(", ")}）`)}async function h(t){if(t.dir)return[{id:null,dir:r(i(t.dir))}];const e=a({project:t.project}),o=new Map(e.map(t=>[t.target.id,t]));if(t.target){const r="all"===t.target?n.map(t=>t.id):t.target.split(",").map(t=>t.trim()).filter(t=>t.length>0),i=r.filter(t=>!c(t));return i.length>0?void u.error(`未知的 --target: ${i.join(", ")}（可选: ${n.map(t=>t.id).join("、")}、all）`):r.filter(c).flatMap(t=>{const r=o.get(t);return r?[{id:t,dir:r.skillsDir}]:[]})}if(!process.stdin.isTTY||!process.stderr.isTTY)return void u.error("非交互模式需要指定 --target 或 --dir");const s=e.flatMap(t=>c(t.target.id)?[{item:t,id:t.target.id}]:[]);return(await m.multiselect({message:"选择要安装到的 orchestrator（空格勾选，回车确认）",options:s.map(({item:t,id:r})=>({value:r,label:`${t.target.label}（${t.skillsDir}）`,...t.present?{}:{hint:"未检测到使用痕迹"}})),initialValues:s.filter(({item:t})=>t.present).map(({id:t})=>t),required:!0})).flatMap(t=>{const r=o.get(t);return r?[{id:t,dir:r.skillsDir}]:[]})}

package/dist/cli/commands/skills.js

@@ -1 +1 @@
-var t=this&&this.__rewriteRelativeImportExtension||function(t,e){return"string"==typeof t&&/^\.\.?\//.test(t)?t.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i,function(t,s,i,r,n){return s?e?".jsx":".js":!i||r&&n?i+r+"."+n.toLowerCase()+"js":t}):t};import{defineCommand as e}from"citty";const s=import.meta.url.endsWith(".ts")?"ts":"js";function i(e){const i=new URL(`./${e}.${s}`,import.meta.url).href;return import(t(i)).then(t=>t.default)}export default e({meta:{description:"读取已注册 Agent 的 SKILL.md（list/get/path）"},subCommands:{list:()=>i("skills-list"),get:()=>i("skills-get"),path:()=>i("skills-path")}});
+var t=this&&this.__rewriteRelativeImportExtension||function(t,s){return"string"==typeof t&&/^\.\.?\//.test(t)?t.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i,function(t,e,i,r,l){return e?s?".jsx":".js":!i||r&&l?i+r+"."+l.toLowerCase()+"js":t}):t};import{defineCommand as s}from"citty";const e=import.meta.url.endsWith(".ts")?"ts":"js";function i(s){const i=new URL(`./${s}.${e}`,import.meta.url).href;return import(t(i)).then(t=>t.default)}export default s({meta:{description:"读取已注册 Agent 的 SKILL.md（list/get/path），或安装 skill 到 orchestrator 目录（install）"},subCommands:{list:()=>i("skills-list"),get:()=>i("skills-get"),path:()=>i("skills-path"),install:()=>i("skills-install")}});

package/dist/cli/index.js

@@ -1 +1 @@
-var t=this&&this.__rewriteRelativeImportExtension||function(t,e){return"string"==typeof t&&/^\.\.?\//.test(t)?t.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i,function(t,r,o,s,n){return r?e?".jsx":".js":!o||s&&n?o+s+"."+n.toLowerCase()+"js":t}):t};import{defineCommand as e,runMain as r}from"citty";import o from"chalk";import{checkForUpdate as s,getCurrentVersion as n}from"./utils/update-checker.js";import{resolveLogLevelFromArgv as a,setLogLevel as i}from"./utils/output.js";const c=n(),l=import.meta.url.endsWith(".ts")?"ts":"js";function u(e){const r=new URL(`./commands/${e}.${l}`,import.meta.url).href;return import(t(r)).then(t=>t.default)}const m=e({meta:{name:"roll",version:c,description:"花卷 Agent — 轻量级 Agent 编排系统"},args:{verbose:{type:"boolean",alias:"v",description:"输出调试日志",default:!1}},subCommands:{agent:()=>u("agent"),run:()=>u("run"),ask:()=>u("ask"),chat:()=>u("chat"),config:()=>u("config"),skills:()=>u("skills"),browser:()=>u("browser"),doctor:()=>u("doctor"),update:()=>u("update")}}),p=s({allowNetwork:!1}).catch(()=>{});i(a(process.argv.slice(2))),r(m).then(()=>{p.then(t=>{t?.hasUpdate&&console.error(`\n${o.yellow("⬆")} roll ${o.green(`v${t.latest}`)} available (current: v${t.current}). Run ${o.cyan("roll update")} to upgrade.`)}).catch(()=>{})});
+var t=this&&this.__rewriteRelativeImportExtension||function(t,e){return"string"==typeof t&&/^\.\.?\//.test(t)?t.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i,function(t,r,o,s,n){return r?e?".jsx":".js":!o||s&&n?o+s+"."+n.toLowerCase()+"js":t}):t};import{defineCommand as e,runMain as r}from"citty";import o from"chalk";import{checkForUpdate as s,getCurrentVersion as n}from"./utils/update-checker.js";import{resolveLogLevelFromArgv as a,setLogLevel as i}from"./utils/output.js";const c=n(),l=import.meta.url.endsWith(".ts")?"ts":"js";function u(e){const r=new URL(`./commands/${e}.${l}`,import.meta.url).href;return import(t(r)).then(t=>t.default)}const p=e({meta:{name:"roll",version:c,description:"花卷 Agent — 轻量级 Agent 编排系统"},args:{verbose:{type:"boolean",alias:"v",description:"输出调试日志",default:!1}},subCommands:{agent:()=>u("agent"),run:()=>u("run"),ask:()=>u("ask"),chat:()=>u("chat"),config:()=>u("config"),setup:()=>u("setup"),skills:()=>u("skills"),browser:()=>u("browser"),doctor:()=>u("doctor"),update:()=>u("update")}}),m=s({allowNetwork:!1}).catch(()=>{});i(a(process.argv.slice(2))),r(p).then(()=>{m.then(t=>{t?.hasUpdate&&console.error(`\n${o.yellow("⬆")} roll ${o.green(`v${t.latest}`)} available (current: v${t.current}). Run ${o.cyan("roll update")} to upgrade.`)}).catch(()=>{})});