Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(plugins): 插件 /agent-models 可按位置读远程模型

PraiseZhuccb1ee17073a
diff --git a/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-agent-models.md b/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-agent-models.md
index 3da505a5c8..1f1ad33974 100644
--- a/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-agent-models.md
+++ b/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-agent-models.md
@@ -1,9 +1,8 @@
## 4.0.3a 只读 Agent 模型目录
-设置页、panel、mainView 和电子脑均可 GET 同源 `/agent-models`(不接受参数)。
-返回 `{ok:true,models:[{id,name,agent,providerId,providerName,efforts,defaultEffort,visible}]}`。
-visible 跟随当前账号模型选择器;建议默认显示可见项,隐藏项由用户展开。旧 Host 缺此字段时兼容原列表。
+设置页、panel、mainView 和电子脑均可 GET 同源 `/agent-models`。无参时返回本机已连接且可用于新任务的模型,并追加 `locations:[{agentDeviceId,name}]`(同账号其他电脑与生效中的供应商分享,不含本机;读不到位置时省略该字段)。可选查询参数只有 `agent_device_id`:带上后只投影那台位置允许远程调用的来源,响应回显 `agentDeviceId`。同一模型在不同来源下是多项。
+返回 `{ok:true,models:[{id,name,agent,providerId,providerName,efforts,defaultEffort,visible}],agentDeviceId?,locations?}`。
+无参时 visible 跟随当前账号模型选择器;带参时 visible 用模型目录默认值,不套本机开关。建议默认显示可见项,隐藏项由用户展开。旧 Host 缺这些字段时兼容原列表。
每项为独立的模型×框架×来源;空 efforts 与 null defaultEffort 表示未声明,不得猜测。
-只包含本机已连接且可用于新任务的模型,不代表远程 SSH 目录。读取不调用模型、
-不触发凭证认领或上游发现,不返回凭证、账号 identity 或 endpoint;不需要新增 manifest 权限。
-旧 Host 可能返回 404,插件应明确提示升级;503 时提供重试。运行前再次核验选定来源。
+不代表远程 SSH 目录。读取不调用模型、不触发凭证认领或上游发现,不返回凭证、账号 identity 或 endpoint;不需要新增 manifest 权限。
+格式非法、重复参数或其他查询参数返回 400。格式合法但那台离线、未知或没开远程控制时返回 503 且 `errorCode` 为 `NOT_AVAILABLE`,响应里没有本机条目。旧 Host 带任何参数都返回 400。旧 Host 可能返回 404,插件应明确提示升级;503 时提供重试。运行前再次核验选定来源。
diff --git a/apps/desktop/src/main/cindy-brain/__tests__/ghostAgentModels.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/ghostAgentModels.test.ts
index 14cf054ca6..342c113eec 100644
--- a/apps/desktop/src/main/cindy-brain/__tests__/ghostAgentModels.test.ts
+++ b/apps/desktop/src/main/cindy-brain/__tests__/ghostAgentModels.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from 'vitest';
import type { ProviderView } from '@cindy/model-providers';
-import { projectGhostAgentModels } from '../ghostAgentModels.js';
+import { createGhostAgentModelsCache, projectGhostAgentModels } from '../ghostAgentModels.js';
const provider = (id: string, efforts: string[]) =>
({
@@ -105,4 +105,37 @@ describe('plugin model projection', () => {
const after = projectGhostAgentModels([p], ['codex', 'pi']);
expect(after.ok && after.models.map(m => m.agent)).toEqual(['codex', 'pi']);
});
+
+ it('projects a remote location with catalog defaults and distinct provider rows', async () => {
+ const anthropic = provider('anthropic', ['high']);
+ const api = provider('anthropic-api', ['high']);
+ anthropic.models.codex![0]!.defaultEnabled = false;
+ const result = await createGhostAgentModelsCache().catalog('owner', 'claude', async () => [anthropic, api]);
+ expect(result).toEqual({
+ ok: true,
+ agentDeviceId: 'claude',
+ models: [
+ {
+ visible: false,
+ id: 'model',
+ name: 'Model',
+ agent: 'codex',
+ providerId: 'anthropic',
+ providerName: 'anthropic',
+ efforts: ['high'],
+ defaultEffort: 'high',
+ },
+ {
+ visible: true,
+ id: 'model',
+ name: 'Model',
+ agent: 'codex',
+ providerId: 'anthropic-api',
+ providerName: 'anthropic-api',
+ efforts: ['high'],
+ defaultEffort: 'high',
+ },
+ ],
+ });
+ });
});
diff --git a/apps/desktop/src/main/cindy-brain/ghostAgentModels.ts b/apps/desktop/src/main/cindy-brain/ghostAgentModels.ts
index cd4bf4216d..8c7adbd673 100644
--- a/apps/desktop/src/main/cindy-brain/ghostAgentModels.ts
+++ b/apps/desktop/src/main/cindy-brain/ghostAgentModels.ts
@@ -6,10 +6,15 @@ import {
} from '@cindy/model-providers';
import type { GhostAgentModelsResult } from '../../shared/ghost.js';
+export const GHOST_AGENT_MODELS_CACHE_MS = 60_000;
+export const GHOST_REMOTE_AGENT_MODELS = ['codex', 'claude-code', 'pi'] as const;
+export type GhostAgentLocation = { agentDeviceId: string; name: string };
+type GhostAgentModelsOk = Extract<GhostAgentModelsResult, { ok: true }>;
+
/** Project each provider separately: the same model can support different efforts per route. */
export function projectGhostAgentModels(views: ProviderView[], availableAgents: readonly string[], visibilityOverride: (agent: 'codex' | 'claude-code' | 'pi', providerId: string, modelId: string) => boolean | undefined = () => undefined): GhostAgentModelsResult {
- const models: Extract<GhostAgentModelsResult, { ok: true }>['models'] = [];
- for (const agent of ['codex', 'claude-code', 'pi'] as const) {
+ const models: GhostAgentModelsOk['models'] = [];
+ for (const agent of GHOST_REMOTE_AGENT_MODELS) {
if (!availableAgents.includes(agent)) continue;
for (const provider of connectedProvidersForAgent(views, agent)) {
for (const model of provider.models[agent] ?? []) {
@@ -30,3 +35,42 @@ export function projectGhostAgentModels(views: ProviderView[], availableAgents:
}
return { ok: true, models };
}
+
+/** Plugin GET /agent-models caches successful locations and per-device catalogs for 60s. */
+export function createGhostAgentModelsCache(options: { now?: () => number; ttlMs?: number } = {}) {
+ const now = options.now ?? Date.now;
+ const ttlMs = options.ttlMs ?? GHOST_AGENT_MODELS_CACHE_MS;
+ let locations: { owner: string; at: number; value: GhostAgentLocation[] } | null = null;
+ const catalogs = new Map<string, { at: number; value: GhostAgentModelsOk }>();
+
+ return {
+ async locations(owner: string, read: () => Promise<GhostAgentLocation[]>): Promise<GhostAgentLocation[] | undefined> {
+ if (locations && locations.owner === owner && now() - locations.at < ttlMs) return locations.value;
+ try {
+ const value = await read();
+ locations = { owner, at: now(), value };
+ return value;
+ } catch {
+ return undefined;
+ }
+ },
+ async catalog(
+ owner: string,
+ agentDeviceId: string,
+ read: () => Promise<ProviderView[]>,
+ ): Promise<GhostAgentModelsResult> {
+ const key = `${owner}\0${agentDeviceId}`;
+ const hit = catalogs.get(key);
+ if (hit && now() - hit.at < ttlMs) return hit.value;
+ try {
+ const projected = projectGhostAgentModels(await read(), GHOST_REMOTE_AGENT_MODELS);
+ if (!projected.ok) return { ok: false, errorCode: 'NOT_AVAILABLE', message: 'Model catalog unavailable' };
+ const value = { ...projected, agentDeviceId };
+ catalogs.set(key, { at: now(), value });
+ return value;
+ } catch {
+ return { ok: false, errorCode: 'NOT_AVAILABLE', message: 'Model catalog unavailable' };
+ }
+ },
+ };
+}
diff --git a/apps/desktop/src/main/cindy-brain/index.ts b/apps/desktop/src/main/cindy-brain/index.ts
index 8afd01d5eb..17ccdcc5ad 100644
--- a/apps/desktop/src/main/cindy-brain/index.ts
+++ b/apps/desktop/src/main/cindy-brain/index.ts
@@ -77,7 +77,7 @@ async function resolveMobilePluginMedia(instanceId: string, url: string, current
return file && /^[a-f0-9]{64}\.[a-z0-9]+$/.test(file) ? { path: `/media/${file}`, mediaKind: result.kind } : null;
}
import { getModelVisibilityOverride, waitForModelVisibilityMirror } from '../maker-host/model-visibility-mirror.js';
-import { projectGhostAgentModels } from './ghostAgentModels.js';
+import { createGhostAgentModelsCache, projectGhostAgentModels } from './ghostAgentModels.js';
import { getDesktopProviderService } from '../maker-host/createDesktopProviderService.js';
import { PluginDownloadSlot } from './downloadSlot.js';
import { createDownloader } from '../downloader/index.js';
@@ -571,6 +571,7 @@ import {
isOrganizationManagedProvider,
isProviderDisabled,
type MediaCapability,
+ type ProviderView,
xaiApiOfficialRuntimeAgents,
XAI_API_CUSTOM_PROVIDER_ID,
} from '@cindy/model-providers';
@@ -2164,6 +2165,19 @@ export function setGhostAgentTurnRunner(runner: GhostAgentTurnRunner | null): vo
getGhostAgentSlot().setRunner(runner);
}
+const ghostAgentModelsCache = createGhostAgentModelsCache();
+let listGhostAgentLocations: (() => Promise<Array<{ agentDeviceId: string; name: string }>>) | null = null;
+let readGhostAgentRemoteViews: ((agentDeviceId: string) => Promise<ProviderView[]>) | null = null;
+
+/** maker-ipc 注入设备列表与跨设备目录读取;静态 import device-link 会成环。 */
+export function setGhostAgentModelLocationSources(sources: {
+ listLocations: () => Promise<Array<{ agentDeviceId: string; name: string }>>;
+ readRemoteViews: (agentDeviceId: string) => Promise<ProviderView[]>;
+} | null): void {
+ listGhostAgentLocations = sources?.listLocations ?? null;
+ readGhostAgentRemoteViews = sources?.readRemoteViews ?? null;
+}
+
/** maker-ipc 完成初始化后注入「切到这条可见任务」;保持 cindy-brain 不反向依赖 deepLink。 */
export function setGhostSessionRevealer(reveal: ((sessionId: string) => void) | null): void {
getGhostAgentSlot().setRevealSession(reveal);
@@ -8299,11 +8313,22 @@ export function registerGhostIpc(): void {
setGhostSandboxDevToolsDisabled(app.isPackaged);
setGhostAppContextProvider(currentGhostAppContext);
setGhostMediaModelsProvider(getGhostConfigurableMediaModels);
- setGhostAgentModelsProvider(async (instanceId) => {
+ setGhostAgentModelsProvider(async (instanceId, agentDeviceId) => {
const owner = activeOwnerScopeKey();
if (!findGhostForInstanceId(instanceId)?.enabled) {
return { ok: false, errorCode: 'NOT_AVAILABLE', message: 'Plugin unavailable' };
}
+ if (agentDeviceId !== undefined) {
+ const readRemote = readGhostAgentRemoteViews;
+ if (!readRemote) {
+ return { ok: false, errorCode: 'NOT_AVAILABLE', message: 'Model catalog unavailable' };
+ }
+ const catalog = await ghostAgentModelsCache.catalog(owner, agentDeviceId, () => readRemote(agentDeviceId));
+ if (owner !== activeOwnerScopeKey() || !findGhostForInstanceId(instanceId)?.enabled) {
+ return { ok: false, errorCode: 'NOT_AVAILABLE', message: 'Plugin unavailable' };
+ }
+ return catalog;
+ }
const views = await getDesktopProviderService({ allowSideEffects: false }).listProviders({ allowSideEffects: false, snapshotOnly: true });
if (owner !== activeOwnerScopeKey() || !findGhostForInstanceId(instanceId)?.enabled) {
return { ok: false, errorCode: 'NOT_AVAILABLE', message: 'Plugin unavailable' };
@@ -8316,7 +8341,13 @@ export function registerGhostIpc(): void {
if (owner !== activeOwnerScopeKey() || !findGhostForInstanceId(instanceId)?.enabled || !maker) {
return { ok: false, errorCode: 'NOT_AVAILABLE', message: 'Model runtimes unavailable' };
}
- return projectGhostAgentModels(views, maker.listAvailableAgents(), getModelVisibilityOverride);
+ const projected = projectGhostAgentModels(views, maker.listAvailableAgents(), getModelVisibilityOverride);
+ if (!projected.ok || !listGhostAgentLocations) return projected;
+ const locations = await ghostAgentModelsCache.locations(owner, listGhostAgentLocations);
+ if (owner !== activeOwnerScopeKey() || !findGhostForInstanceId(instanceId)?.enabled) {
+ return { ok: false, errorCode: 'NOT_AVAILABLE', message: 'Plugin unavailable' };
+ }
+ return locations ? { ...projected, locations } : projected;
});
// 面板唤醒电子脑(cindy-ghost://<id>/wake 供片分支):面板零桥,唤醒经它
// 自己的协议通道进来。只对"已装且唤醒"的意识放行;熔断态不清账(重载 /
diff --git a/apps/desktop/src/main/cindy-brain/runtime/__tests__/electronSandboxAdapter.ownerPartition.test.ts b/apps/desktop/src/main/cindy-brain/runtime/__tests__/electronSandboxAdapter.ownerPartition.test.ts
index a4dd4456cd..910fd188c4 100644
--- a/apps/desktop/src/main/cindy-brain/runtime/__tests__/electronSandboxAdapter.ownerPartition.test.ts
+++ b/apps/desktop/src/main/cindy-brain/runtime/__tests__/electronSandboxAdapter.ownerPartition.test.ts
@@ -133,6 +133,8 @@ import {
setGhostSecretsHandler,
setGhostMediaModelsProvider,
} from '../electronSandboxAdapter';
+import { createGhostAgentModelsCache } from '../../ghostAgentModels.js';
+import type { ProviderView } from '@cindy/model-providers';
function ghost(id: string): InstalledGhost {
return {
@@ -798,6 +800,7 @@ describe('electronSandboxAdapter owner partition', () => {
});
describe('read-only agent model directory', () => {
+ // 测试价值:生产入口 protocolHandler GET /agent-models;#7452 远程位置/400/503/60s 缓存;原用例只覆盖无参。tier=unit
it('identifies the organization instance when a root plugin has the same id', async () => {
const provider = vi.fn().mockResolvedValue({ ok: true, models: [] });
setGhostAgentModelsProvider(provider);
@@ -840,6 +843,139 @@ describe('read-only agent model directory', () => {
expect((await pending).status).toBe(403);
expect((await handler(new Request('cindy-ghost://agent-owner/agent-models'))).status).toBe(403);
});
+
+ it('appends locations on unparameterized GET and still calls the provider with one argument', async () => {
+ const provider = vi.fn().mockResolvedValue({
+ ok: true,
+ models: [{ id: 'local', name: 'Local', agent: 'codex', providerId: 'p', providerName: 'P', efforts: [], defaultEffort: null }],
+ locations: [{ agentDeviceId: 'claude', name: 'Claude' }],
+ });
+ setGhostAgentModelsProvider(provider);
+ ensureGhostProtocolRegistered(ghost('agent-locations'));
+ const handler = harness.sessions.get(approvedPartition('cindy-ghost-owner:cloud:opaque-owner-a:agent-locations'))!.protocolHandler!;
+ const response = await handler(new Request('cindy-ghost://agent-locations/agent-models'));
+ expect(response.status).toBe(200);
+ expect(provider).toHaveBeenCalledExactlyOnceWith('agent-locations');
+ expect(await response.json()).toEqual({
+ ok: true,
+ models: [{ id: 'local', name: 'Local', agent: 'codex', providerId: 'p', providerName: 'P', efforts: [], defaultEffort: null }],
+ locations: [{ agentDeviceId: 'claude', name: 'Claude' }],
+ });
+ });
+
+ it('rejects duplicate, empty, oversized, or extra query parameters with 400', async () => {
+ const provider = vi.fn().mockResolvedValue({ ok: true, models: [{ id: 'local' }] });
+ setGhostAgentModelsProvider(provider);
+ ensureGhostProtocolRegistered(ghost('agent-bad-query'));
+ const handler = harness.sessions.get(approvedPartition('cindy-ghost-owner:cloud:opaque-owner-a:agent-bad-query'))!.protocolHandler!;
+ for (const path of [
+ 'agent-models?agent_device_id=a&agent_device_id=b',
+ 'agent-models?agent_device_id=',
+ `agent-models?agent_device_id=${'x'.repeat(129)}`,
+ 'agent-models?agent_device_id=ok&extra=1',
+ ]) {
+ const response = await handler(new Request('cindy-ghost://agent-bad-query/' + path));
+ expect(response.status).toBe(400);
+ expect(await response.text()).toBe('');
+ }
+ expect(provider).not.toHaveBeenCalled();
+ });
+
+ it('reads a remote location, echoes agentDeviceId, and keeps no-store GET-only constraints', async () => {
+ const provider = vi.fn().mockResolvedValue({
+ ok: true,
+ agentDeviceId: 'claude',
+ models: [
+ { id: 'opus', name: 'Opus', agent: 'claude-code', providerId: 'anthropic', providerName: 'Anthropic', efforts: ['high'], defaultEffort: 'high', visible: true },
+ { id: 'opus', name: 'Opus', agent: 'claude-code', providerId: 'anthropic-api', providerName: 'Anthropic API', efforts: ['high'], defaultEffort: 'high', visible: true },
+ ],
+ });
+ setGhostAgentModelsProvider(provider);
+ ensureGhostProtocolRegistered(ghost('agent-remote'));
+ const handler = harness.sessions.get(approvedPartition('cindy-ghost-owner:cloud:opaque-owner-a:agent-remote'))!.protocolHandler!;
+ const response = await handler(new Request('cindy-ghost://agent-remote/agent-models?agent_device_id=claude'));
+ expect(response.status).toBe(200);
+ expect(response.headers.get('cache-control')).toBe('no-store');
+ expect(provider).toHaveBeenCalledExactlyOnceWith('agent-remote', 'claude');
+ expect(await response.json()).toEqual({
+ ok: true,
+ agentDeviceId: 'claude',
+ models: [
+ { id: 'opus', name: 'Opus', agent: 'claude-code', providerId: 'anthropic', providerName: 'Anthropic', efforts: ['high'], defaultEffort: 'high', visible: true },
+ { id: 'opus', name: 'Opus', agent: 'claude-code', providerId: 'anthropic-api', providerName: 'Anthropic API', efforts: ['high'], defaultEffort: 'high', visible: true },
+ ],
+ });
+ expect((await handler(new Request('cindy-ghost://agent-remote/agent-models?agent_device_id=claude', { method: 'POST' }))).status).toBe(405);
+ });
+
+ it('returns 503 NOT_AVAILABLE without local models when a well-formed location cannot be read', async () => {
+ const provider = vi.fn().mockResolvedValue({ ok: false, errorCode: 'NOT_AVAILABLE', message: 'Model catalog unavailable' });
+ setGhostAgentModelsProvider(provider);
+ ensureGhostProtocolRegistered(ghost('agent-missing'));
+ const handler = harness.sessions.get(approvedPartition('cindy-ghost-owner:cloud:opaque-owner-a:agent-missing'))!.protocolHandler!;
+ const response = await handler(new Request('cindy-ghost://agent-missing/agent-models?agent_device_id=offline-box'));
+ expect(response.status).toBe(503);
+ expect(provider).toHaveBeenCalledExactlyOnceWith('agent-missing', 'offline-box');
+ const body = await response.json();
+ expect(body).toEqual({ ok: false, errorCode: 'NOT_AVAILABLE', message: 'Model catalog unavailable' });
+ expect(JSON.stringify(body)).not.toMatch(/endpoint|apiKey|local/);
+ });
+
+ it('does not deliver an in-flight parameterized catalog after owner changes', async () => {
+ let finish!: (value: { ok: true; models: []; agentDeviceId: string }) => void;
+ setGhostAgentModelsProvider(() => new Promise(resolve => { finish = resolve; }));
+ ensureGhostProtocolRegistered(ghost('agent-remote-owner'));
+ const handler = harness.sessions.get(approvedPartition('cindy-ghost-owner:cloud:opaque-owner-a:agent-remote-owner'))!.protocolHandler!;
+ const pending = handler(new Request('cindy-ghost://agent-remote-owner/agent-models?agent_device_id=claude'));
+ harness.activeOwner = { mode: 'cloud', dataOwnerId: 'owner-b', generation: 2 };
+ finish({ ok: true, models: [], agentDeviceId: 'claude' });
+ expect((await pending).status).toBe(403);
+ });
+
+ it('caches successful locations and remote catalogs for 60s and does not cache failures', async () => {
+ let now = 1_000;
+ const listLocations = vi.fn()
+ .mockRejectedValueOnce(new Error('cloud down'))
+ .mockResolvedValue([{ agentDeviceId: 'claude', name: 'Claude' }]);
+ const readRemote = vi.fn()
+ .mockRejectedValueOnce(new Error('offline'))
+ .mockResolvedValue([] as ProviderView[]);
+ const cache = createGhostAgentModelsCache({ now: () => now });
+ setGhostAgentModelsProvider(async (_id, agentDeviceId) => {
+ if (agentDeviceId) return cache.catalog('owner-a', agentDeviceId, () => readRemote());
+ const locations = await cache.locations('owner-a', listLocations);
+ return { ok: true, models: [], ...(locations ? { locations } : {}) };
+ });
+ ensureGhostProtocolRegistered(ghost('agent-cache'));
+ const handler = harness.sessions.get(approvedPartition('cindy-ghost-owner:cloud:opaque-owner-a:agent-cache'))!.protocolHandler!;
+ const noArg = () => handler(new Request('cindy-ghost://agent-cache/agent-models'));
+ const withArg = () => handler(new Request('cindy-ghost://agent-cache/agent-models?agent_device_id=claude'));
+
+ expect(await (await noArg()).json()).toEqual({ ok: true, models: [] });
+ expect(listLocations).toHaveBeenCalledTimes(1);
+ expect(await (await noArg()).json()).toEqual({
+ ok: true, models: [], locations: [{ agentDeviceId: 'claude', name: 'Claude' }],
+ });
+ expect(listLocations).toHaveBeenCalledTimes(2);
+ now += 30_000;
+ await noArg();
+ expect(listLocations).toHaveBeenCalledTimes(2);
+ now += 30_000;
+ await noArg();
+ expect(listLocations).toHaveBeenCalledTimes(3);
+
+ now = 100_000;
+ expect((await withArg()).status).toBe(503);
+ expect(readRemote).toHaveBeenCalledTimes(1);
+ expect(await (await withArg()).json()).toMatchObject({ ok: true, agentDeviceId: 'claude' });
+ expect(readRemote).toHaveBeenCalledTimes(2);
+ now += 30_000;
+ await withArg();
+ expect(readRemote).toHaveBeenCalledTimes(2);
+ now += 30_000;
+ await withArg();
+ expect(readRemote).toHaveBeenCalledTimes(3);
+ });
});
it('rejects failed in-flight model reads after owner changes', async () => {
diff --git a/apps/desktop/src/main/cindy-brain/runtime/electronSandboxAdapter.ts b/apps/desktop/src/main/cindy-brain/runtime/electronSandboxAdapter.ts
index 82aa3fd620..b2c22e6d6d 100644
--- a/apps/desktop/src/main/cindy-brain/runtime/electronSandboxAdapter.ts
+++ b/apps/desktop/src/main/cindy-brain/runtime/electronSandboxAdapter.ts
@@ -279,9 +279,9 @@ export function setGhostMediaModelsProvider(
ghostMediaModelsProvider = provider;
}
-let ghostAgentModelsProvider: ((ghostId: string) => Promise<GhostAgentModelsResult>) | null = null;
+let ghostAgentModelsProvider: ((ghostId: string, agentDeviceId?: string) => Promise<GhostAgentModelsResult>) | null = null;
export function setGhostAgentModelsProvider(
- provider: (ghostId: string) => Promise<GhostAgentModelsResult>,
+ provider: (ghostId: string, agentDeviceId?: string) => Promise<GhostAgentModelsResult>,
): void {
ghostAgentModelsProvider = provider;
}
@@ -583,10 +583,22 @@ function registerGhostProtocol(
if (url.pathname === '/agent-models') {
const headers = { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' };
if (request.method !== 'GET') return new Response(null, { status: 405, headers });
- if (url.search) return new Response(null, { status: 400, headers });
+ const keys = [...url.searchParams.keys()];
+ const ids = url.searchParams.getAll('agent_device_id');
+ let agentDeviceId: string | undefined;
+ if (keys.length > 0) {
+ if (keys.length !== 1 || keys[0] !== 'agent_device_id' || ids.length !== 1) {
+ return new Response(null, { status: 400, headers });
+ }
+ const id = ids[0];
+ if (!id || id.length > 128) return new Response(null, { status: 400, headers });
+ agentDeviceId = id;
+ }
if (!ghostAgentModelsProvider) return new Response(null, { status: 503, headers });
try {
- const result = await ghostAgentModelsProvider(storagePart);
+ const result = agentDeviceId === undefined
+ ? await ghostAgentModelsProvider(storagePart)
+ : await ghostAgentModelsProvider(storagePart, agentDeviceId);
if (!isGhostProtocolOwnerActive(owner)) return new Response(null, { status: 403, headers });
return new Response(JSON.stringify(result), {
status: result.ok ? 200 : result.errorCode === 'PERMISSION_DENIED' ? 403 : 503,
diff --git a/apps/desktop/src/main/maker-ipc/__tests__/workerAgentLocations.test.ts b/apps/desktop/src/main/maker-ipc/__tests__/workerAgentLocations.test.ts
new file mode 100644
index 0000000000..b4dc42553f
--- /dev/null
+++ b/apps/desktop/src/main/maker-ipc/__tests__/workerAgentLocations.test.ts
@@ -0,0 +1,87 @@
+/**
+ * 测试价值
+ * - 生产入口与可观察结果:listWorkerAgentLocations() 列出同账号可执行电脑与 active 分享,不含本机
+ * - Bug/规则依据:makecindy/cindy#7452 SC1,与 list_available_models 的 locations 同源
+ * - 现有覆盖缺口:原实现是 register.ts 内部闭包,抽出后无行为测试
+ * - 最小失败输入:本机/离线设备、paused 分享、设备列表抛错
+ * - tier:unit
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { DeviceLinkDeviceView } from '../../../shared/deviceLinkIpc.js';
+
+const io = vi.hoisted(() => ({
+ handleListDevices: vi.fn(),
+ getReceivedShares: vi.fn(() => [] as Array<{
+ shareId: string;
+ status: 'active' | 'paused';
+ providerLabel: string;
+ owner: { displayName: string };
+ }>),
+ providerShareAgentDeviceId: vi.fn((id: string) => `share:${id}`),
+}));
+
+vi.mock('../../device-link/ipc.js', () => ({
+ handleListDevices: io.handleListDevices,
+ defaultDeps: vi.fn(() => ({})),
+}));
+vi.mock('../../device-link/providerShareGuest.js', () => ({
+ getReceivedShares: io.getReceivedShares,
+ providerShareAgentDeviceId: io.providerShareAgentDeviceId,
+}));
+
+import { listWorkerAgentLocations } from '../workerAgentLocations.js';
+
+function device(overrides: Partial<DeviceLinkDeviceView>): DeviceLinkDeviceView {
+ return {
+ deviceId: 'mac-mini',
+ name: 'Mac mini',
+ platform: 'darwin',
+ appVersion: '1.0.0',
+ lastSeenAt: null,
+ online: true,
+ busy: false,
+ remoteControlEnabled: true,
+ controlEnabled: true,
+ isSelf: false,
+ ...overrides,
+ };
+}
+
+describe('listWorkerAgentLocations', () => {
+ beforeEach(() => {
+ io.handleListDevices.mockReset();
+ io.getReceivedShares.mockReset();
+ io.providerShareAgentDeviceId.mockClear();
+ io.handleListDevices.mockResolvedValue({ devices: [] });
+ io.getReceivedShares.mockReturnValue([]);
+ });
+
+ it('lists online remote-control computers and active shares, excluding this computer', async () => {
+ io.handleListDevices.mockResolvedValue({
+ devices: [
+ device({}),
+ device({ deviceId: 'self', name: 'This Mac', isSelf: true }),
+ device({ deviceId: 'offline', name: 'Offline', online: false }),
+ device({ deviceId: 'phone', name: 'iPhone', platform: 'ios' }),
+ ],
+ });
+ io.getReceivedShares.mockReturnValue([
+ { shareId: 's1', status: 'active', providerLabel: 'Claude API', owner: { displayName: 'Ann' } },
+ { shareId: 's2', status: 'paused', providerLabel: 'Paused', owner: { displayName: 'Bob' } },
+ ]);
+ await expect(listWorkerAgentLocations()).resolves.toEqual([
+ { agentDeviceId: 'mac-mini', name: 'Mac mini' },
+ { agentDeviceId: 'share:s1', name: 'Claude API · Ann' },
+ ]);
+ });
+
+ it('omits computers when the device list fails and still returns active shares', async () => {
+ io.handleListDevices.mockRejectedValue(new Error('cloud down'));
+ io.getReceivedShares.mockReturnValue([
+ { shareId: 's1', status: 'active', providerLabel: 'Claude API', owner: { displayName: 'Ann' } },
+ ]);
+ await expect(listWorkerAgentLocations()).resolves.toEqual([
+ { agentDeviceId: 'share:s1', name: 'Claude API · Ann' },
+ ]);
+ });
+});
diff --git a/apps/desktop/src/main/maker-ipc/register.ts b/apps/desktop/src/main/maker-ipc/register.ts
index e0c3c7682d..56de74bbd7 100644
--- a/apps/desktop/src/main/maker-ipc/register.ts
+++ b/apps/desktop/src/main/maker-ipc/register.ts
@@ -1065,8 +1065,8 @@ import {
createOrcaRemoteWorkerSessionOpener,
registerOrcaRemoteWorkerHandlers,
} from './orcaRemoteWorkerHost.js';
-import { createOrcaRemoteWorkers, invokeDeviceValue, isExecutionDeviceCandidate, type OrcaRemoteWorkers } from './orcaRemoteWorkers.js';
-import { getReceivedShares, providerShareAgentDeviceId } from '../device-link/providerShareGuest.js';
+import { createOrcaRemoteWorkers, invokeDeviceValue, type OrcaRemoteWorkers } from './orcaRemoteWorkers.js';
+import { listWorkerAgentLocations } from './workerAgentLocations.js';
import {
ORCA_EXECUTION_DEVICES_CHANNEL,
ORCA_REMOTE_WORKER_BRIDGE_CHANNEL,
@@ -1501,6 +1501,7 @@ import {
setGhostErrandRunner,
setGhostWorkspaceSessionService,
setGhostLibraryExtraDirSync,
+ setGhostAgentModelLocationSources,
getFocusedGhostSessionId,
notifyGhostSessionEvent,
getInstalledGhostName,
@@ -14634,6 +14635,10 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
// 的会话聚焦通道。注入方式与 setGhostAgentTurnRunner 同款倒置,避免
// cindy-brain 反向依赖 maker-ipc / localDb 形成模块环。
setGhostLibraryExtraDirSync(syncLibraryReadonlyExtraDir);
+ setGhostAgentModelLocationSources({
+ listLocations: listWorkerAgentLocations,
+ readRemoteViews: (agentDeviceId) => readDeviceProviderViews(remoteBackgroundInvoke, agentDeviceId),
+ });
getGhostFsSlot().setSessionSnapshotResolver(async (sessionId, instanceId) =>
resolveGhostFsSessionSnapshot((id) => getMaker().getSession(id), sessionId, instanceId));
setGhostWorkspaceSessionService({
@@ -15743,31 +15748,6 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
return { devices: await orcaRemoteWorkers.listExecutionDevices() };
});
- /**
- * Lead 的 list_available_models 给出的 Worker Agent 位置(远程供应商):同账号在线、开了远程控制的
- * 电脑,以及收到的、未暂停的分享。只列位置不读目录;那台没开放供应商时按位置再列模型会是空的。
- * 分享不写分享者的电脑名(provider-sharing.md §6),写「供应商 · 分享者」。
- */
- async function listWorkerAgentLocations(): Promise<Array<{ agentDeviceId: string; name: string }>> {
- const { devices } = await handleListDevices(deviceDirectoryDeps()).catch(() => ({ devices: [] }));
- const shares = getReceivedShares().filter((share) => share.status === 'active');
- return [
- ...devices
- .filter(isExecutionDeviceCandidate)
- .map((device) => ({ agentDeviceId: device.deviceId, name: device.name || device.deviceId })),
- ...shares.flatMap((share) => {
- try {
- return [{
- agentDeviceId: providerShareAgentDeviceId(share.shareId),
- name: `${share.providerLabel} · ${share.owner.displayName}`,
- }];
- } catch {
- return [];
- }
- }),
- ];
- }
-
const getProviderRoutingContext = () =>
readOrcaWorkerProviderRoutingContext({
providerService: getDesktopProviderService(),
diff --git a/apps/desktop/src/main/maker-ipc/workerAgentLocations.ts b/apps/desktop/src/main/maker-ipc/workerAgentLocations.ts
new file mode 100644
index 0000000000..54a137daf9
--- /dev/null
+++ b/apps/desktop/src/main/maker-ipc/workerAgentLocations.ts
@@ -0,0 +1,31 @@
+import { handleListDevices, defaultDeps as deviceDirectoryDeps } from '../device-link/ipc.js';
+import { getReceivedShares, providerShareAgentDeviceId } from '../device-link/providerShareGuest.js';
+import { isExecutionDeviceCandidate } from './orcaRemoteWorkers.js';
+
+export type WorkerAgentLocation = { agentDeviceId: string; name: string };
+
+/**
+ * Lead 的 list_available_models 与插件 GET /agent-models 共用的 Worker Agent 位置:
+ * 同账号在线、开了远程控制的电脑,以及收到的、未暂停的分享。只列位置不读目录;
+ * 那台没开放供应商时按位置再列模型会是空的。分享不写分享者的电脑名
+ * (provider-sharing.md §6),写「供应商 · 分享者」。不含本机。
+ */
+export async function listWorkerAgentLocations(): Promise<WorkerAgentLocation[]> {
+ const { devices } = await handleListDevices(deviceDirectoryDeps()).catch(() => ({ devices: [] }));
+ const shares = getReceivedShares().filter((share) => share.status === 'active');
+ return [
+ ...devices
+ .filter(isExecutionDeviceCandidate)
+ .map((device) => ({ agentDeviceId: device.deviceId, name: device.name || device.deviceId })),
+ ...shares.flatMap((share) => {
+ try {
+ return [{
+ agentDeviceId: providerShareAgentDeviceId(share.shareId),
+ name: `${share.providerLabel} · ${share.owner.displayName}`,
+ }];
+ } catch {
+ return [];
+ }
+ }),
+ ];
+}
diff --git a/apps/desktop/src/shared/ghost.ts b/apps/desktop/src/shared/ghost.ts
index e8ae407e24..d94e93d271 100644
--- a/apps/desktop/src/shared/ghost.ts
+++ b/apps/desktop/src/shared/ghost.ts
@@ -7086,7 +7086,7 @@ export interface GhostAppContextResult {
};
}
-/** Read-only local agent routes. No credentials or provider configuration. */
+/** Read-only agent routes. No credentials or provider configuration. */
export type GhostAgentModelsResult =
| {
ok: true;
@@ -7100,6 +7100,8 @@ export type GhostAgentModelsResult =
efforts: string[];
defaultEffort: string | null;
}>;
+ agentDeviceId?: string;
+ locations?: Array<{ agentDeviceId: string; name: string }>;
}
| { ok: false; errorCode: 'PERMISSION_DENIED' | 'NOT_AVAILABLE'; message: string };
diff --git a/docs/dev-rules/orca-team-architecture.md b/docs/dev-rules/orca-team-architecture.md
index 9f56eeb69d..7af2461589 100644
--- a/docs/dev-rules/orca-team-architecture.md
+++ b/docs/dev-rules/orca-team-architecture.md
@@ -508,7 +508,7 @@ Worker turn 被 vendor 报终止型 error,但 interrupted-turn auto-resume 仍
Worker 的展示角色名 `role`(1-32 字符)与 team 内唯一标识 `label`(slug,`/^[a-z0-9_-]+$/i`,≤32)在创建后可通过 `update_worker` / `maker:worker:update` 修改。改名不是换执行单元:Agent、模型、权限、工作目录与已发起的 turn 都不受影响,也**不允许**借改名实施中途换模型(见坑点 #6)。`label` 唯一性由 `uniq_orca_workers_team_label` 最终把关(约束范围含已归档 worker),冲突必须回 `DUPLICATE_LABEL` 且零副作用;空操作必须 idempotent。同一 Worker 的读-改-写必须按 worker id 串行化,避免 UI 改 role 与 Lead 改 label 的并发请求互相完整回写覆盖;UI 保存时也只能提交用户实际改过的字段(服务端锁拦不住请求自带的旧值)。插件 team plan 以 label 冻结 Worker 归属与委派自动授权且登记后整体不可变:未结算计划条目引用到的 label(旧值或新值)不允许改名,必须回 `WORKER_STATE_CHANGED`,role 改名不受影响;插件已卸载(任务归属确实撤销)后保留的收据不再构成锁;停用 / 未批准可恢复、重新启用后计划仍会继续,故仍保持锁定(fail closed)。当 worker session 标题仍是 `orcaWorkerSessionTitle` 生成形态(`Worker · role · label`,role 与 label 相同时去重为 `Worker · role`)时同步改写为新形态;用户自定义/重命名过的标题不得被覆盖。成功的改名必须广播 `ORCA_WORKER_CHANGED`,并同步 worker session 的 `local-db:sessions:patched`(若标题被改写)。实现指针:`orcaTeamService.ts` 的 `updateWorker`、`orcaTeamStore.ts` 的 `updateWorkerIdentity`、`pluginTaskService.ts` 的 `isTeamPlanLabelLocked` / `isTeamPlanLabelLockedByReceipt`、`orcaWorkerCreationService.ts` 的 `orcaWorkerTitle`、`packages/lizi-mcps/src/xdt-helper/update_worker.ts`。
11. **Worker 的 Agent 位置:远程供应商与本机供应商一视同仁(状态:不变量,2026-10-10 用户裁决)**
- 与上一条「运行设备」不同,这里任务、目录、命令与文件都留在 Lead 所在电脑,只有 Worker 的 Agent 在另一台同账号电脑或分享来的供应商上运行(与普通任务的远程 Agent 同一机制,`sessions.agent_device_id`)。每个 Worker 可以单独选位置:`OrcaWorkerCreateParams.agentDeviceId` 不传 = 跟 Lead(旧调用方、旧控制端与 MCP 省略时都走这里),`null` = 任务所在电脑,string = 那台电脑或 `share:<id>`;等于本机设备 id 时按 `null`。模型与来源按 Worker 自己的位置读目录(那台只列允许被远程调用的供应商),只有与 Lead 同一位置时才沿用 Lead 的来源(来源 id 在不同电脑上不是一回事);Agent 在另一台时不按本机的 Cindy AI key 判预算模型。那台读不到目录在占槽与启动前失败(`REMOTE_AGENT_DEVICE_UNREACHABLE` / `REMOTE_AGENT_SHARE_*`),不回退到本机。SSH Lead 不能指定另一台(`INVALID_PARAMS`);跨设备 Worker 创建时可以指定独立的 Agent 电脑,`agentDeviceId` 相对工作电脑解释,省略或 null 使用工作电脑默认,不继承 Lead。工作电脑先按所选供应商电脑的目录准入,复用普通任务的远程 Agent 与工具执行通道,不迁移工作目录,插件任务只能跟 Lead 或留在任务所在电脑。入口一处一套:桌面「创建 Worker / 开启协同」弹窗与新建任务用同一个模型面板,任务所在电脑的供应商之后列其他电脑与分享(`useWorkerAgentDevices`),选中哪一行 Worker 的 Agent 就在哪运行,默认选中 Lead 的位置;选择远程供应商后仍保留工作电脑入口;切换工作电脑先恢复该电脑本机默认,随后可选择它能调用的远程供应商或分享。旧版工作电脑不开放独立 Agent 位置,显式请求不能被静默忽略。桌面手动选择模型并提交创建后,在 `workerCreationPrefs.modelSelectionByHost` 按账号与任务所在电脑保存完整选择(Agent、模型、来源、Agent 所在电脑、推理强度与 Fast),下次打开优先恢复,不被 Lead 后续换模型或换位置覆盖;未手动选择时仍跟随 Lead 的位置,取消未提交的编辑不保存。旧版逐 Agent 记忆继续可读,不推测它原先属于哪台电脑;SSH 与运行设备的临时选择不写入这份位置记忆。远程选择不覆盖旧版逐 Agent 的本机目录记忆,模型行的档位预设仍使用 `agentDeviceModelMemory`。回归见 `CreateWorkerPopover.test.tsx` 的重新打开与任务所在电脑隔离用例。手机同样支持选择 Agent 位置(`useOrcaWorkerForm` 的 `agentDeviceId`,模型面板 `remote` 与新建任务同一份 `useRemoteAgentCatalogs`),通过 `orcaWorkerPrefs.modelSelectionByHost` 在手机本地按账号与任务所在电脑保存同样的完整选择,创建成功或确认新任务协同草稿后写回;异步读取不能覆盖已编辑的表单。恢复的来源或模型不可用时保留原路线,由界面阻止或宿主明确拒绝,不静默换到别处;旧端不能兑现位置时同样拒绝。回归见 `useOrcaWorkerForm.test.tsx` 与 `orcaTeam.test.ts`。被控电脑声明 `supportsOrcaWorkerAgentDevice` 时新建任务的远程供应商与协同不再互斥。Lead 的 `list_available_models` 可按 `agent_device_id` 列那里的模型并给出 `locations`,`create_worker` / `create_workers` 用同一个 `agent_device_id`。Worker 列表投影 `session.agentDeviceId`,桌面 Worker 头像叠与远程任务同款的单波纹 + 点;手机 Worker 行保持原来的状态圆点,不加远程标识(2026-10-11 用户要求维持原样)。已开始的 Lead 与 Worker 可以由用户在模型列表里换 Agent 位置(本机供应商、其他电脑、分享来的供应商一起列出),与普通任务同一套换电脑事务:选择先登记为意图,下一次发送边界全量交接后在新位置重建,协同身份不变(2026-10-16 用户裁决:任务都在本机,只换供应商所在电脑,不应排除)。运行设备 Worker 与 SSH 任务仍不开放;被控电脑上的协同任务暂不在控制端开放(旧版被控端会拒绝),手机端同样暂未开放。供应商组为任务换电脑见第 12 条。实现指针:`orcaWorkerCreationService.ts` 的 `resolveWorkerAgentDeviceId` / `agentDeviceCatalogFailure`,`register.ts` 的 `listWorkerAgentLocations` 与 `listAvailableModels`,renderer `CreateWorkerPopover.tsx`、`hooks/useWorkerAgentDevices.ts`;协议见 `protocol-compatibility.md`「协同 Worker 的 Agent 位置」。
+ 与上一条「运行设备」不同,这里任务、目录、命令与文件都留在 Lead 所在电脑,只有 Worker 的 Agent 在另一台同账号电脑或分享来的供应商上运行(与普通任务的远程 Agent 同一机制,`sessions.agent_device_id`)。每个 Worker 可以单独选位置:`OrcaWorkerCreateParams.agentDeviceId` 不传 = 跟 Lead(旧调用方、旧控制端与 MCP 省略时都走这里),`null` = 任务所在电脑,string = 那台电脑或 `share:<id>`;等于本机设备 id 时按 `null`。模型与来源按 Worker 自己的位置读目录(那台只列允许被远程调用的供应商),只有与 Lead 同一位置时才沿用 Lead 的来源(来源 id 在不同电脑上不是一回事);Agent 在另一台时不按本机的 Cindy AI key 判预算模型。那台读不到目录在占槽与启动前失败(`REMOTE_AGENT_DEVICE_UNREACHABLE` / `REMOTE_AGENT_SHARE_*`),不回退到本机。SSH Lead 不能指定另一台(`INVALID_PARAMS`);跨设备 Worker 创建时可以指定独立的 Agent 电脑,`agentDeviceId` 相对工作电脑解释,省略或 null 使用工作电脑默认,不继承 Lead。工作电脑先按所选供应商电脑的目录准入,复用普通任务的远程 Agent 与工具执行通道,不迁移工作目录,插件任务只能跟 Lead 或留在任务所在电脑。入口一处一套:桌面「创建 Worker / 开启协同」弹窗与新建任务用同一个模型面板,任务所在电脑的供应商之后列其他电脑与分享(`useWorkerAgentDevices`),选中哪一行 Worker 的 Agent 就在哪运行,默认选中 Lead 的位置;选择远程供应商后仍保留工作电脑入口;切换工作电脑先恢复该电脑本机默认,随后可选择它能调用的远程供应商或分享。旧版工作电脑不开放独立 Agent 位置,显式请求不能被静默忽略。桌面手动选择模型并提交创建后,在 `workerCreationPrefs.modelSelectionByHost` 按账号与任务所在电脑保存完整选择(Agent、模型、来源、Agent 所在电脑、推理强度与 Fast),下次打开优先恢复,不被 Lead 后续换模型或换位置覆盖;未手动选择时仍跟随 Lead 的位置,取消未提交的编辑不保存。旧版逐 Agent 记忆继续可读,不推测它原先属于哪台电脑;SSH 与运行设备的临时选择不写入这份位置记忆。远程选择不覆盖旧版逐 Agent 的本机目录记忆,模型行的档位预设仍使用 `agentDeviceModelMemory`。回归见 `CreateWorkerPopover.test.tsx` 的重新打开与任务所在电脑隔离用例。手机同样支持选择 Agent 位置(`useOrcaWorkerForm` 的 `agentDeviceId`,模型面板 `remote` 与新建任务同一份 `useRemoteAgentCatalogs`),通过 `orcaWorkerPrefs.modelSelectionByHost` 在手机本地按账号与任务所在电脑保存同样的完整选择,创建成功或确认新任务协同草稿后写回;异步读取不能覆盖已编辑的表单。恢复的来源或模型不可用时保留原路线,由界面阻止或宿主明确拒绝,不静默换到别处;旧端不能兑现位置时同样拒绝。回归见 `useOrcaWorkerForm.test.tsx` 与 `orcaTeam.test.ts`。被控电脑声明 `supportsOrcaWorkerAgentDevice` 时新建任务的远程供应商与协同不再互斥。Lead 的 `list_available_models` 可按 `agent_device_id` 列那里的模型并给出 `locations`,`create_worker` / `create_workers` 用同一个 `agent_device_id`。Worker 列表投影 `session.agentDeviceId`,桌面 Worker 头像叠与远程任务同款的单波纹 + 点;手机 Worker 行保持原来的状态圆点,不加远程标识(2026-10-11 用户要求维持原样)。已开始的 Lead 与 Worker 可以由用户在模型列表里换 Agent 位置(本机供应商、其他电脑、分享来的供应商一起列出),与普通任务同一套换电脑事务:选择先登记为意图,下一次发送边界全量交接后在新位置重建,协同身份不变(2026-10-16 用户裁决:任务都在本机,只换供应商所在电脑,不应排除)。运行设备 Worker 与 SSH 任务仍不开放;被控电脑上的协同任务暂不在控制端开放(旧版被控端会拒绝),手机端同样暂未开放。供应商组为任务换电脑见第 12 条。实现指针:`orcaWorkerCreationService.ts` 的 `resolveWorkerAgentDeviceId` / `agentDeviceCatalogFailure`,`workerAgentLocations.ts` 的 `listWorkerAgentLocations` 与 `register.ts` 的 `listAvailableModels`,renderer `CreateWorkerPopover.tsx`、`hooks/useWorkerAgentDevices.ts`;协议见 `protocol-compatibility.md`「协同 Worker 的 Agent 位置」。
12. **协同任务归供应商组,换电脑不丢回报(状态:不变量,2026-10-10 用户裁决)**
Lead 与 Worker 与普通任务一样归供应商组分配、出问题时自动换电脑(产品口径见 `docs/product-rules/provider-groups.md` §6.1「协同任务」),只有审查任务仍排除(`readProviderGroupSessionRow`)。要点:
diff --git a/docs/dev-rules/plugin-security-and-authoring.md b/docs/dev-rules/plugin-security-and-authoring.md
index 8c6c930098..ef7550899f 100644
--- a/docs/dev-rules/plugin-security-and-authoring.md
+++ b/docs/dev-rules/plugin-security-and-authoring.md
@@ -920,13 +920,18 @@ IPC 时追加对应专项规则要求的验证。
### 只读 Agent 模型目录
插件自己的同源 `GET /agent-models` 面向 settings、panel、mainView 与电子脑。
-无需新增 manifest 权限,不改变存量批准状态。仅投影已连接来源中可用于新任务的本机
-`id/name/agent/providerId/providerName/efforts/defaultEffort/visible`,来源级强度不能被跨来源合并。
-visible 复用当前账号模型选择器的用户开关与目录默认值;隐藏项保留供显式展开,偏好未就绪不伪造默认。
-使用 ProviderService 的 `allowSideEffects:false` 读取,不主动发现或认领凭证,不调用模型。
-不暴露 ProviderView、auth、账号 identity 或 endpoint;响应 no-store、仅 GET、无参数,
-检查插件在装启用与 owner 归属,异步返回前复核。旧 Host 404 时插件应明确提示升级。
-此端点不覆盖远程 SSH 模型,执行前仍需核验真实路由。
+无需新增 manifest 权限,不改变存量批准状态。无参时投影已连接来源中可用于新任务的本机
+`id/name/agent/providerId/providerName/efforts/defaultEffort/visible`,并追加 `locations`
+(同账号其他电脑与生效中的供应商分享,不含本机;读失败则省略)。可选查询参数只有
+`agent_device_id`:带上后读那台允许远程调用的来源并回显 `agentDeviceId`,不查 `locations`。
+来源级强度不能被跨来源合并。无参 visible 复用当前账号模型选择器的用户开关与目录默认值;
+带参 visible 只用模型目录默认值,不套本机开关。隐藏项保留供显式展开,偏好未就绪不伪造默认。
+使用 ProviderService 的 `allowSideEffects:false` 读取本机清单;带参经 `readDeviceProviderViews`
+跨设备读取。不主动发现或认领凭证,不调用模型。不暴露 ProviderView、auth、账号 identity 或 endpoint;
+响应 no-store、仅 GET。其他参数、重复参数、空或超过 128 字符的 id 返回 400;格式合法但读不到
+(离线、未知、没开远程控制)返回 503 且 `errorCode` 为 `NOT_AVAILABLE`,响应里没有本机条目。
+旧 Host 带任何参数都返回 400。检查插件在装启用与 owner 归属,异步返回前复核。
+旧 Host 404 时插件应明确提示升级。此端点不覆盖远程 SSH 模型,执行前仍需核验真实路由。
### 同账号插件资料同步
diff --git a/docs/dev-rules/protocol-compatibility.md b/docs/dev-rules/protocol-compatibility.md
index 10bebbe7d3..a8232f2f5f 100644
--- a/docs/dev-rules/protocol-compatibility.md
+++ b/docs/dev-rules/protocol-compatibility.md
@@ -770,6 +770,10 @@ device-link 授权、撤权与 owner fence;仅有归属范围权限的调用
SSH 主机不自动成为设备目录成员。实现与回归见 `mcp-integrations/historyDevices.ts`、
`localDb/ipc/historyQuery.ts` 和 `packages/lizi-mcps/src/__tests__/historyDevices.test.ts`。
+## 插件 Agent 模型目录的运行位置(2026-10-27)
+
+插件同源 `GET /agent-models` 新增可选查询参数 `agent_device_id`(Agent 在哪台同账号电脑或分享来的供应商上;省略 = 本机清单)。无参响应在原 `models` 上追加 `locations: [{agentDeviceId, name}]`,与 Lead `list_available_models` 的 `locations` 同源(同账号在线且开了远程控制的电脑 + 生效中的供应商分享,不含本机);位置列表读失败时仍返回 200,只省略 `locations`。带参时只投影那台允许远程调用的来源,响应回显 `agentDeviceId`,不附 `locations`。旧 Host 仍拒绝任何查询字符串,带参返回 400;新 Host 其它参数、重复参数、空或超过 128 字符的 id 同样 400。格式合法但那台离线、未知或没开远程控制时返回 503 且 `errorCode` 为 `NOT_AVAILABLE`,响应里没有本机条目,旧客户端应退回无参本机清单。不覆盖 SSH 远程主机目录,不改变 `create_worker` / `agent_device_id` 派工校验。实现与回归见 `electronSandboxAdapter.ts`、`ghostAgentModels.ts`、`workerAgentLocations.ts`。
+
## 定时任务的 Agent 运行位置(2026-10-22)
`maker:schedule:*` 读回的定时任务与写入参数新增可选 `agentDeviceId`(每次新建任务时 Agent 在哪台电脑或