feat: add one-time agent permission setup

README.md

@@ -247,6 +247,7 @@ open dist/boss-agent.app
 - `boss-agent.app` 是本机 `local-agent` 的 macOS WebView 外壳，默认打开 `http://127.0.0.1:4317/boss-agent`
 - 未绑定账号时会显示可扫码的 Boss APP 绑定二维码；已绑定后显示账号、API、服务器、授权、本机权限获取和本机 Skill 部署情况
 - 本机权限会区分两级判断：`辅助功能 / 屏幕录制 / 自动化控制` 只代表核心桌面控制能力；完整接管还需要按业务场景补齐全磁盘访问、输入监控、通知、麦克风、摄像头和本地网络等权限
+- 本机权限页提供“一次完整授权”入口，点击后通过 `GET /api/v1/boss-agent/permissions/open?target=all` 打开 macOS 隐私设置；各权限项也有独立设置入口。授权完成后由系统持久保存，后续控制过程只静默校验并使用，不在任务执行中临时申请
 - 本机状态 JSON 可通过 `GET http://127.0.0.1:4317/api/v1/boss-agent/status` 查看，不会返回设备 token 明文
 
 device-agent 当前职责：

local-agent/boss-agent-status.mjs

@@ -63,6 +63,21 @@ const EXTENDED_PERMISSION_DEFS = [
   },
 ];
 
+const MACOS_PERMISSION_SETTINGS = {
+  all: "x-apple.systempreferences:com.apple.preference.security?Privacy",
+  accessibility: "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility",
+  screenRecording: "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture",
+  automation: "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation",
+  fullDiskAccess: "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles",
+  inputMonitoring: "x-apple.systempreferences:com.apple.preference.security?Privacy_ListenEvent",
+  notifications: "x-apple.systempreferences:com.apple.Notifications-Settings.extension",
+  microphone: "x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone",
+  camera: "x-apple.systempreferences:com.apple.preference.security?Privacy_Camera",
+  localNetwork: "x-apple.systempreferences:com.apple.preference.security?Privacy_LocalNetwork",
+};
+
+const AUTO_PREFLIGHT_PERMISSION_KEYS = new Set(["accessibility", "screenRecording", "automation"]);
+
 function nonEmpty(value) {
   const text = String(value ?? "").trim();
   return text || undefined;
@@ -195,6 +210,41 @@ function resolvePermissionReadiness(coreItems, extendedItems) {
   };
 }
 
+function buildPermissionSetupPlan(coreItems, extendedItems, readiness) {
+  const actions = [...coreItems, ...extendedItems].map((item) => ({
+    key: item.key,
+    label: item.label,
+    description: item.description,
+    tier: item.tier,
+    status: item.status,
+    requiredForSilentControl: true,
+    canPreflight: AUTO_PREFLIGHT_PERMISSION_KEYS.has(item.key),
+    settingsUrl: MACOS_PERMISSION_SETTINGS[item.key] ?? MACOS_PERMISSION_SETTINGS.all,
+    openUrl: `/api/v1/boss-agent/permissions/open?target=${encodeURIComponent(item.key)}`,
+    owner: "boss-agent / local-agent",
+  }));
+  const missingActions = actions.filter((action) => action.status !== "granted");
+
+  return {
+    mode: "one_time_setup",
+    title: "一次完整授权",
+    goal: "首次把完整接管需要的权限集中配置好，后续控制过程中只做状态校验和静默使用。",
+    silentUseReady: missingActions.length === 0,
+    primaryAction: {
+      label: "打开完整授权向导",
+      href: "/api/v1/boss-agent/permissions/open?target=all",
+      settingsUrl: MACOS_PERMISSION_SETTINGS.all,
+    },
+    actions,
+    missingKeys: missingActions.map((action) => action.key),
+    summary: readiness.fullControlReady
+      ? "完整授权已满足，后续可静默执行。"
+      : "仍有权限未确认，请在首次配置阶段一次性补齐，避免后续任务执行中断。",
+    persistenceNote:
+      "macOS 会把授权持久写入系统隐私数据库；除非用户撤销授权、重装应用或更换运行时签名，否则后续控制不需要重复申请。",
+  };
+}
+
 function resolveSkills(runtime) {
   const rawSkills = Array.isArray(runtime.lastSkills) ? runtime.lastSkills : [];
   const items = rawSkills
@@ -229,6 +279,7 @@ export function buildBossAgentStatus(config = {}, runtime = {}, options = {}) {
   const corePermissionItems = permissionItems(PERMISSION_DEFS, permissions);
   const extendedPermissionItems = permissionItems(EXTENDED_PERMISSION_DEFS, permissions);
   const permissionReadiness = resolvePermissionReadiness(corePermissionItems, extendedPermissionItems);
+  const permissionSetup = buildPermissionSetupPlan(corePermissionItems, extendedPermissionItems, permissionReadiness);
 
   return {
     appName: "boss-agent",
@@ -265,6 +316,7 @@ export function buildBossAgentStatus(config = {}, runtime = {}, options = {}) {
       extendedItems: extendedPermissionItems,
     },
     permissionReadiness,
+    permissionSetup,
     skills: resolveSkills(runtime),
   };
 }
@@ -333,10 +385,30 @@ function sidebarPermissionBlock(status) {
           <b class="${fullTone}">${escapeHtml(`${readiness.extendedGrantedCount}/${readiness.extendedTotal}`)}</b>
         </div>
         <div class="sidebar-note">${escapeHtml(missingExtended ? `完整接管还需：${missingExtended}` : "完整接管权限已满足")}</div>
+        <a class="sidebar-action" href="${escapeHtml(status.permissionSetup.primaryAction.href)}">${escapeHtml(status.permissionSetup.title)}</a>
         <div class="sidebar-mini-list">${permissionRows(status.permissions.items)}</div>
       </section>`;
 }
 
+function setupActionRows(status) {
+  return status.permissionSetup.actions
+    .map((action) => {
+      const tone = statusTone(action.status);
+      const preflight = action.canPreflight ? "可预触发" : "需手动开启";
+      return `<div class="setup-action">
+        <div>
+          <div class="permission-name">${escapeHtml(action.label)}</div>
+          <div class="muted">${escapeHtml(action.description)} · ${escapeHtml(preflight)}</div>
+        </div>
+        <div class="setup-action-right">
+          <span class="pill ${tone}">${escapeHtml(permissionText(action.status))}</span>
+          <a class="text-link" href="${escapeHtml(action.openUrl)}">打开设置</a>
+        </div>
+      </div>`;
+    })
+    .join("");
+}
+
 function skillRows(status) {
   const skills = status.skills?.items ?? [];
   if (skills.length === 0) {
@@ -503,6 +575,17 @@ function renderBossAgentHtmlBase(status, options = {}) {
       font-weight: 800;
     }
     .nav a.active .nav-badge { background: rgba(7, 193, 96, .14); color: #058743; }
+    .sidebar-action {
+      display: block;
+      padding: 9px 10px;
+      border-radius: 12px;
+      background: var(--green);
+      color: #fff;
+      text-align: center;
+      text-decoration: none;
+      font-size: 12px;
+      font-weight: 850;
+    }
     .sidebar-card {
       display: grid;
       gap: 10px;
@@ -580,7 +663,7 @@ function renderBossAgentHtmlBase(status, options = {}) {
     .timer { color: var(--muted); font-size: 13px; }
     .panel { padding: 22px; }
     .rows { display: grid; gap: 14px; margin-top: 18px; }
-    .row, .permission-row, .skill-row { display: flex; justify-content: space-between; gap: 18px; align-items: center; }
+    .row, .permission-row, .skill-row, .setup-action { display: flex; justify-content: space-between; gap: 18px; align-items: center; }
     .label, .muted { color: var(--muted); font-size: 13px; }
     .value { font-weight: 750; text-align: right; }
     .cards { display: grid; grid-template-columns: repeat(4, 1fr); gap: 14px; margin-bottom: 18px; }
@@ -601,6 +684,24 @@ function renderBossAgentHtmlBase(status, options = {}) {
     .pill.bad { color: var(--bad); background: var(--bad-soft); }
     .permission-name { font-weight: 780; margin-bottom: 3px; }
     .skill-name { font-weight: 780; margin-bottom: 3px; }
+    .setup-panel { margin-bottom: 18px; }
+    .setup-head { display: flex; justify-content: space-between; gap: 18px; align-items: flex-start; }
+    .setup-head p { margin: 8px 0 0; color: var(--muted); line-height: 1.65; font-size: 14px; }
+    .setup-actions { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 12px; margin-top: 18px; }
+    .setup-action {
+      padding: 14px;
+      border: 1px solid var(--line);
+      border-radius: 16px;
+      background: #fbfcfb;
+    }
+    .setup-action-right { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }
+    .text-link {
+      color: #058743;
+      text-decoration: none;
+      font-size: 12px;
+      font-weight: 850;
+      white-space: nowrap;
+    }
     .empty-state {
       min-height: 120px;
       display: grid;
@@ -626,6 +727,7 @@ function renderBossAgentHtmlBase(status, options = {}) {
       .window { width: 100vw; min-height: 100vh; border-radius: 0; grid-template-columns: 1fr; }
       .sidebar { display: none; }
       .grid, .lower { grid-template-columns: 1fr; }
+      .setup-actions { grid-template-columns: 1fr; }
       .cards { grid-template-columns: repeat(2, 1fr); }
     }
   </style>
@@ -706,6 +808,18 @@ function renderBossAgentHtmlBase(status, options = {}) {
         </div>
       </section>
 
+      <section class="card panel setup-panel">
+        <div class="setup-head">
+          <div>
+            <h2>${escapeHtml(status.permissionSetup.title)}</h2>
+            <p>${escapeHtml(status.permissionSetup.goal)} 当前状态：${escapeHtml(status.permissionSetup.summary)} 后续静默使用依赖系统持久授权。</p>
+          </div>
+          <a class="button" href="${escapeHtml(status.permissionSetup.primaryAction.href)}">${escapeHtml(status.permissionSetup.primaryAction.label)}</a>
+        </div>
+        <div class="setup-actions">${setupActionRows(status)}</div>
+        <div class="hint">${escapeHtml(status.permissionSetup.persistenceNote)}</div>
+      </section>
+
       <section class="lower">
         <div class="card panel">
           <h2>授权信息</h2>
@@ -757,6 +871,30 @@ function runCommand(command, args, timeoutMs = 2500) {
   });
 }
 
+export function resolveBossAgentPermissionSettingsUrl(target = "all") {
+  return MACOS_PERMISSION_SETTINGS[target] ?? MACOS_PERMISSION_SETTINGS.all;
+}
+
+export async function openBossAgentPermissionSettings(target = "all", platform = process.platform) {
+  const settingsUrl = resolveBossAgentPermissionSettingsUrl(target);
+  if (platform !== "darwin") {
+    return {
+      ok: false,
+      target,
+      settingsUrl,
+      message: "当前平台暂不支持自动打开系统隐私设置，请在系统设置中手动完成授权。",
+    };
+  }
+
+  const result = await runCommand("open", [settingsUrl], 2500);
+  return {
+    ok: result.ok,
+    target,
+    settingsUrl,
+    message: result.ok ? "已打开系统权限设置。" : result.stderr || result.stdout || "打开系统权限设置失败。",
+  };
+}
+
 export async function detectLocalComputerPermissions(platform = process.platform) {
   if (platform !== "darwin") {
     return {

local-agent/server.mjs

@@ -41,6 +41,7 @@ import {
 import {
   buildBossAgentStatus,
   detectLocalComputerPermissions,
+  openBossAgentPermissionSettings,
   renderBossAgentHtmlWithQr,
 } from "./boss-agent-status.mjs";
 import {
@@ -1029,6 +1030,20 @@ const server = createServer(async (request, response) => {
     return;
   }
 
+  if (requestUrl.pathname === "/api/v1/boss-agent/permissions/open") {
+    const target = requestUrl.searchParams.get("target") || "all";
+    const result = await openBossAgentPermissionSettings(target);
+    const wantsJson = String(request.headers.accept || "").includes("application/json");
+    if (wantsJson) {
+      response.writeHead(result.ok ? 200 : 500, { "Content-Type": "application/json" });
+      response.end(JSON.stringify(result));
+      return;
+    }
+    response.writeHead(302, { Location: "/boss-agent" });
+    response.end();
+    return;
+  }
+
   if (requestUrl.pathname === "/health") {
     response.writeHead(200, { "Content-Type": "application/json" });
     response.end(

tests/boss-agent-status.test.mjs

@@ -54,6 +54,13 @@ test("boss-agent status exposes unbound QR binding and local permission states",
   assert.equal(status.permissionReadiness.coreReady, false);
   assert.equal(status.permissionReadiness.fullControlReady, false);
   assert.match(status.permissionReadiness.summary, /完整接管/);
+  assert.equal(status.permissionSetup.mode, "one_time_setup");
+  assert.equal(status.permissionSetup.silentUseReady, false);
+  assert.equal(status.permissionSetup.actions.some((action) => action.key === "fullDiskAccess"), true);
+  assert.equal(
+    status.permissionSetup.actions.every((action) => action.settingsUrl.startsWith("x-apple.systempreferences:")),
+    true,
+  );
   assert.deepEqual(
     status.permissions.items.map((item) => [item.key, item.status]),
     [
@@ -113,6 +120,10 @@ test("boss-agent status treats token-backed devices as bound and renders enterpr
   assert.match(html, /企业电脑接入端/);
   assert.match(html, /本机权限获取/);
   assert.match(html, /完整接管待补齐/);
+  assert.match(html, /一次完整授权/);
+  assert.match(html, /后续静默使用/);
+  assert.match(html, /api\/v1\/boss-agent\/permissions\/open\?target=all/);
+  assert.match(html, /api\/v1\/boss-agent\/permissions\/open\?target=fullDiskAccess/);
   assert.match(html, /Skill/);
   assert.match(html, /bb-browser/);
   assert.match(html, /DeepSeek V4/);