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。

fix(plugin): 保留未来能力声明并后置运行时支持判定

liugaowei9524fe151723
diff --git a/apps/desktop/src/main/cindy-brain/__tests__/ghostHostSetupRequirements.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/ghostHostSetupRequirements.test.ts
index 7403180722..350695079a 100644
--- a/apps/desktop/src/main/cindy-brain/__tests__/ghostHostSetupRequirements.test.ts
+++ b/apps/desktop/src/main/cindy-brain/__tests__/ghostHostSetupRequirements.test.ts
@@ -1,6 +1,7 @@
import { beforeEach, describe, expect, it } from 'vitest';
import type { GhostManifest } from '../../../shared/ghost';
+import { validateGhostManifest } from '../../../shared/ghost';
import { setMainLocale } from '../../i18n';
import { assessGhostHostSetupRequirements } from '../ghostHostSetupRequirements';
@@ -18,6 +19,14 @@ function manifest(id: string, cindy = false): GhostManifest {
}
describe('assessGhostHostSetupRequirements', () => {
+ it('does not infer model-provider setup from unknown declarations', () => {
+ const parsed = validateGhostManifest({ schemaVersion: 3, minCindyVersion: '0.1.0',
+ id: 'future', name: 'Future', version: '1.0.0', entry: 'main.js',
+ cindy: { future: { enabled: true }, image: ['future-action'] } });
+ expect(parsed.ok).toBe(true);
+ if (!parsed.ok) return;
+ expect(assessGhostHostSetupRequirements(parsed.manifest, { clientConfigReady: () => false })).toEqual([]);
+ });
beforeEach(() => {
setMainLocale('en');
});
diff --git a/apps/desktop/src/main/cindy-brain/__tests__/nodeRuntimeBroker.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/nodeRuntimeBroker.test.ts
index 0ee983bcb6..d6017c648f 100644
--- a/apps/desktop/src/main/cindy-brain/__tests__/nodeRuntimeBroker.test.ts
+++ b/apps/desktop/src/main/cindy-brain/__tests__/nodeRuntimeBroker.test.ts
@@ -1911,6 +1911,24 @@ describe('nodeRuntimeBroker · 权限与协议', () => {
broker.destroyAll();
});
+ it('已接收的悬空 OAuth 声明在运行时拒绝,不读取静态凭证或启动 Worker', async () => {
+ const ghost = fakeGhost();
+ ghost.manifest.node!.secretBindings = [{
+ key: 'access_token', label: 'Account', methods: ['run'], oauthSecret: 'future_account',
+ }];
+ const readSecret = vi.fn();
+ const resolveOauthSecret = vi.fn();
+ const spawnProcess = vi.fn();
+ const broker = new GhostNodeRuntimeBroker({ getGhost: () => ghost, readSecret, resolveOauthSecret, spawnProcess });
+ try {
+ expect(await broker.handleRequest('node-ghost', rpcRequest('run')))
+ .toMatchObject({ ok: false, errorCode: 'PERMISSION_DENIED' });
+ expect(readSecret).not.toHaveBeenCalled();
+ expect(resolveOauthSecret).not.toHaveBeenCalled();
+ expect(spawnProcess).not.toHaveBeenCalled();
+ } finally { broker.destroyAll(); }
+ });
+
it('OAuth 刷新跨越停用再启用时不把旧调用交给新 Worker', async () => {
const ghost = fakeGhost();
ghost.manifest.network = { hosts: ['example.test'], secrets: [{
diff --git a/apps/desktop/src/main/cindy-brain/forge.ts b/apps/desktop/src/main/cindy-brain/forge.ts
index 8a5d58880f..02f0a08a41 100644
--- a/apps/desktop/src/main/cindy-brain/forge.ts
+++ b/apps/desktop/src/main/cindy-brain/forge.ts
@@ -1704,7 +1704,7 @@ my-ghost/
// 声明 false 逐个关闭。当前一批:maximize(撑满内容区)、detach(在独立
// 窗口中打开)、minimize(最小化面板;恢复入口由用户偏好决定为浮动气泡或
// 左侧栏)。标题条本体恒由主机绘制、
- // 关不掉;未知键拒装;position:"tab" 时声明本字段拒装
+ // 关不掉;未知键保留但不生效;position:"tab" 时声明本字段拒装
// 一级主视图是独立能力,见 §4.20。使用时直接声明:
// "mainView": { "title": "工作台", "icon": "puzzle", "html": "main-view.html" }
"settingsHtml": "settings.html", // 可选:设置页「自定义设置区」自绘界面(见 §4.8;声明了用户填的凭证时仍必填,用于长期管理/替换/清除;调用前缺失时主机也会在统一 Setup 卡内联收单,见 §4.7)
@@ -4488,7 +4488,7 @@ Cindy 统一归类、随机选择与排序,同批每个场景和每个插件
也长在这里)。你的 panel.html 只画标题条以下的部分,**不要自己再画一条
标题栏**。不想要某颗系统按钮时在身份卡声明
\`"systemButtons": { "maximize": false, "detach": false, "minimize": false }\`
- 逐个关闭(缺省全开;标题条本体关不掉;未知键拒装;\`position:"tab"\` 由插件页
+ 逐个关闭(缺省全开;标题条本体关不掉;未知键保留但不生效;\`position:"tab"\` 由插件页
自绘头,没有这套标准头,声明本字段拒装);
- 与电子脑同源,用 \`BroadcastChannel('<自定名>')\` 通信(电子脑发,面板收);
- 取自己的媒体:\`cindy-ghost://<id>/media/<指纹><后缀>\`(主机查账验归属,别人的图 404);
@@ -4663,20 +4663,28 @@ Cindy 统一归类、随机选择与排序,同批每个场景和每个插件
- 其余要求(目录命名、审核流程等)以该仓根部的 \`CONTRIBUTING.md\` 为准,提交前
在仓内跑一遍 \`node --test .tests/\` 自查。
-## 9. 常见拒装原因速查
+## 9. 兼容性与常见拒装原因
+
+插件开发不应受当前客户端能力注册进度限制。未知顶层能力、对象扩展字段、能力动作
+与订阅事件保留为声明,不因此阻断发布或安装,也不因此获得执行权限。
+插件必须检查所需接口是否存在并处理不支持响应:可选功能局部降级,必要能力缺失时
+提示升级,不影响其它可用功能;权限拒绝、账号失效和网络错误不能当作不支持绕过。
+\`minCindyVersion\` 是兼容声明与分发依据,不是运行时能力探测;手动安装、旧版
+或其它分发渠道仍可能让不适配客户端安装插件,不能省略上述兼容处理。
+旧客户端已有拒装逻辑无法追改;整体协议格式变化仍受 schemaVersion 校验。
- \`id\` 不合法(大写/下划线/超长)· 声明了 command 但没有 tools · command 与已装意识撞名
· **未声明 command**:不拒装,但插件页"使用"按钮禁用,用户无法通过插件页一键启用
或用 $command 点名;AI 工具调用不受影响(见 §2 说明)
- \`tools\` 为空 · panel 详单缺少实际形态(既没有 html,也不是有效的 tab/停靠配置)
-- mainView.html 文件缺失/路径不安全、icon 不在系统图标白名单,或 mainView 含未知字段
+- mainView.html 文件缺失/路径不安全、icon 不在系统图标白名单
- settingsHtml 路径不合法/文件不在包里 · settingsHeight 越界(160–800)或没配 settingsHtml 单独声明
-- panel.systemButtons 格式错(不是对象、未知键、值非布尔,或 position:"tab" 时声明——插件页内面板没有标准头)
+- panel.systemButtons 格式错(不是对象、已知键的值非布尔,或 position:"tab" 时声明——插件页内面板没有标准头)
- keywords(已废弃字段,旧包兼容保留,新意识别写)有单字词 · kind 写了但不是 "chip"(可省略) · schemaVersion 不是 3 · 缺 minCindyVersion
-- cindy 详单格式错(未知类目/动作、空数组)
+- cindy 详单格式错(已知类目的动作不是合法标识、空数组或重复动作)
- agent 详单格式错(background / errand / schedule 存在但不是 true;基础点击触发请写 \`agent: {}\`)
- node 详单格式错(entry 不是包内 CommonJS .js/.cjs、protocol 不在 json-rpc-stdio / mcp-stdio、
- 写了 command/args/shell/env、resident 又写 idleTimeoutSeconds)
+ resident 又写 idleTimeoutSeconds);未知 command/args/shell/env 只保留,不传给进程启动器
- id 用了 \`cindy-\` / \`filo-\` / \`xd-\` 前缀(官方保留,正式版用户通道拒装;给自己的意识换个前缀)
- network 详单格式错(hosts 缺失/裸 TLD/IP/带端口/通配不在最左、secret 缺 inject、
inject.format 没有 {value} 占位、inject.header 用了 Host/Cookie 等协议关键头、
diff --git a/apps/desktop/src/main/cindy-brain/ghostHostSetupRequirements.ts b/apps/desktop/src/main/cindy-brain/ghostHostSetupRequirements.ts
index 4e07491b01..617de0e626 100644
--- a/apps/desktop/src/main/cindy-brain/ghostHostSetupRequirements.ts
+++ b/apps/desktop/src/main/cindy-brain/ghostHostSetupRequirements.ts
@@ -8,6 +8,7 @@
*/
import type { GhostManifest, GhostSetupAssessmentGroup } from '../../shared/ghost.js';
+import { ghostPermissionItems } from '../../shared/ghost.js';
import { t } from '../i18n.js';
export interface GhostHostSetupRequirementProbes {
@@ -27,7 +28,7 @@ const providers: readonly GhostHostSetupRequirementProvider[] = [
labelKey: 'newChat.pluginSetup.hostRequirements.modelProvider.label',
descriptionKey: 'newChat.pluginSetup.hostRequirements.modelProvider.description',
matches: (manifest) =>
- Object.values(manifest.cindy ?? {}).some((actions) => (actions?.length ?? 0) > 0),
+ ghostPermissionItems(manifest).some((item) => item.kind === 'cindy'),
},
];
diff --git a/apps/desktop/src/shared/__tests__/ghost.forward-compat.test.ts b/apps/desktop/src/shared/__tests__/ghost.forward-compat.test.ts
new file mode 100644
index 0000000000..b070939819
--- /dev/null
+++ b/apps/desktop/src/shared/__tests__/ghost.forward-compat.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { validateGhostManifest, ghostPermissionItems } from '../ghost.js';
+
+const base = {
+ schemaVersion: 3, minCindyVersion: '0.1.0', id: 'future-declarations',
+ name: 'Future declarations', version: '1.0.0', entry: 'main.js',
+};
+const extension = { mode: 'future', options: [1, null, { enabled: true }] };
+
+describe('declaration forward compatibility is not Host authorization', () => {
+ it.each([
+ ['mainView', { html: 'view.html' }],
+ ['panel', { html: 'panel.html' }],
+ ['card', {}],
+ ['agent', {}],
+ ['node', { entry: 'node/worker.cjs', protocol: 'json-rpc-stdio' }],
+ ['preview', { hosts: ['example.test'] }],
+ ['skill', { items: [{ dir: 'skills/demo', name: 'demo', description: 'Demo', future: extension }] }],
+ ['manual', { items: [{ dir: 'manual/demo', name: 'demo', description: 'Demo', future: extension }] }],
+ ['subscribe', {}],
+ ])('preserves unknown %s fields through repeated normalization', (field, declaration) => {
+ const raw = { ...base, [field]: { ...declaration, future: extension } };
+ const result = validateGhostManifest(raw);
+ expect(result.ok, JSON.stringify(result)).toBe(true);
+ if (!result.ok) return;
+ expect(result.manifest[field]).toEqual(raw[field as keyof typeof raw]);
+ expect(validateGhostManifest(result.manifest)).toEqual(result);
+ });
+
+ it('preserves future categories, actions, topics and hooks without requiring known hook lifecycle', () => {
+ const raw = { ...base, cindy: { image: ['generate', 'future-action'], future: extension },
+ subscribe: { topics: ['future-topic'], hooks: ['future-hook'] } };
+ const result = validateGhostManifest(raw);
+ expect(result).toMatchObject({ ok: true, manifest: { cindy: raw.cindy, subscribe: raw.subscribe } });
+ });
+
+ it('keeps prototype-like extension keys as own data without changing object prototypes', () => {
+ const cindy = JSON.parse('{"__proto__":{"polluted":true},"constructor":{"future":true}}');
+ const result = validateGhostManifest({ ...base, cindy });
+ expect(result.ok).toBe(true);
+ if (!result.ok) return;
+ expect(Object.hasOwn(result.manifest.cindy!, '__proto__')).toBe(true);
+ expect(Object.getPrototypeOf(result.manifest.cindy!)).toBe(Object.prototype);
+ expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+ });
+
+ it('preserves unresolved OAuth and future binding metadata for runtime resolution', () => {
+ const binding = { key: 'access_token', label: 'Account', methods: ['run'],
+ oauthSecret: 'future_account', future: extension };
+ const result = validateGhostManifest({ ...base, settingsHtml: 'settings.html',
+ node: { entry: 'node/worker.cjs', protocol: 'json-rpc-stdio', secretBindings: [binding] } });
+ expect(result).toMatchObject({ ok: true, manifest: { node: { secretBindings: [binding] } } });
+ });
+
+ it.each([
+ { mainView: { html: '../escape.html', future: extension } },
+ { card: { externalLinks: 'yes', future: extension } },
+ { agent: { background: 'yes', future: extension } },
+ { node: { entry: '../worker.cjs', protocol: 'json-rpc-stdio', future: extension } },
+ { preview: { hosts: ['https://example.test/path'], future: extension } },
+ { skill: { items: [{ dir: '../escape', name: 'demo', description: 'Demo' }], future: extension } },
+ { cindy: { image: [42], future: extension } },
+ { cindy: { image: ['generate', 'generate'], future: extension } },
+ { subscribe: { topics: [42], future: extension } },
+ { subscribe: { hooks: ['will-user-message'], future: extension } },
+ ])('still rejects malformed known fields and unsafe paths: %j', (fields) => {
+ expect(validateGhostManifest({ ...base, ...fields }).ok).toBe(false);
+ });
+});
+
+it('unknown declarations never become permission items', () => {
+ const result = validateGhostManifest({ ...base, cindy: { future: extension, image: ['future-action'] }, subscribe: { topics: ['future-topic'], hooks: ['future-hook'] } });
+ expect(result.ok).toBe(true);
+ if (!result.ok) return;
+ expect(ghostPermissionItems(result.manifest).filter((item) => item.kind === 'cindy' || item.key.includes('future'))).toEqual([]);
+});
diff --git a/apps/desktop/src/shared/__tests__/ghost.test.ts b/apps/desktop/src/shared/__tests__/ghost.test.ts
index 83b97b6d0f..3cf306057d 100644
--- a/apps/desktop/src/shared/__tests__/ghost.test.ts
+++ b/apps/desktop/src/shared/__tests__/ghost.test.ts
@@ -276,9 +276,11 @@ describe('ghost · 清单校验', () => {
).toEqual({ maximize: false, detach: false, minimize: false });
expect(withPanel({ systemButtons: {} }).ok).toBe(true);
expect(withPanel({ systemButtons: { maximize: true, detach: true } }).ok).toBe(true);
- // 非对象 / 未知键 / 非布尔值:收词明确拒绝(规则 9)
+ // 已知按钮校验类型,未知按钮仅保留声明。
expect(withPanel({ systemButtons: 'off' }).ok).toBe(false);
- expect(withPanel({ systemButtons: { refresh: false } }).ok).toBe(false);
+ expect(withPanel({ systemButtons: { refresh: false } })).toMatchObject({
+ ok: true, manifest: { panel: { systemButtons: { refresh: false } } },
+ });
expect(withPanel({ systemButtons: { maximize: 'no' } }).ok).toBe(false);
expect(withPanel({ systemButtons: { detach: 0 } }).ok).toBe(false);
expect(withPanel({ systemButtons: { minimize: 0 } }).ok).toBe(false);
@@ -1253,7 +1255,7 @@ describe('ghost · 芯片型清单(schemaVersion 2)', () => {
slots: ['panel', 'agent'],
agent: { background: true, command: 'hidden' },
}).ok,
- ).toBe(false);
+ ).toBe(true);
});
it('agent.errand 派活加档:单列高风险权限,可与 background 并存(2026-07-31)', () => {
@@ -1329,7 +1331,7 @@ describe('ghost · 芯片型清单(schemaVersion 2)', () => {
);
});
- it('node 清单拒绝任意命令字段、越界配置和无槽详单;空槽按零能力兼容', () => {
+ it('node 保留未知字段,越界配置和无槽详单仍拒绝;空槽按零能力兼容', () => {
const withNode = (node: unknown, slots: string[] = ['panel', 'node']) =>
validateGhostManifest({ ...goodChipManifest(), slots, node });
expect(withNode({ entry: 'node/a.cjs', protocol: 'json-rpc-stdio' }).ok).toBe(true);
@@ -1338,10 +1340,10 @@ describe('ghost · 芯片型清单(schemaVersion 2)', () => {
expect(withNode({ entry: 'node/a.mjs', protocol: 'json-rpc-stdio' }).ok).toBe(false);
expect(withNode({ entry: 'node/a.cjs', protocol: 'stdio' }).ok).toBe(false);
expect(withNode({ entry: 'node/a.cjs', protocol: 'json-rpc-stdio', command: 'node' }).ok).toBe(
- false,
+ true,
);
expect(withNode({ entry: 'node/a.cjs', protocol: 'json-rpc-stdio', args: ['--x'] }).ok).toBe(
- false,
+ true,
);
expect(
withNode({
@@ -1779,7 +1781,7 @@ describe('ghost · 芯片型清单(schemaVersion 2)', () => {
slots: ['panel', 'main-view'],
mainView: { html: 'main-view.html', position: 'left' },
}),
- ).toMatchObject({ ok: false, reason: expect.stringContaining('不允许的字段') });
+ ).toMatchObject({ ok: true, manifest: { mainView: { position: 'left' } } });
expect(
validateGhostManifest({
...goodChipManifest(),
@@ -1946,17 +1948,13 @@ describe('ghost · cindy 能力详单校验(字段旧名 model 别名兼容)', (
expect(!v.ok && v.reason).toContain('cindy');
});
- it('未知类目 / 未知动作 / 空数组 / 空对象 / 重复动作 / 非对象 → 拒', () => {
+ it('空数组 / 空对象 / 重复动作 / 非对象仍拒绝', () => {
for (const bad of [
- { text: ['complete'] },
- { image: ['upscale'] },
{ image: [] },
{},
{ image: ['generate', 'generate'] },
'image',
- { media: ['upload'] }, // media 类目只有 deposit
{ media: [] },
- { search: ['deep'] },
{ search: [] },
]) {
const v = validateGhostManifest(chipWithModel(bad));
@@ -2028,14 +2026,14 @@ describe('ghost · cindy 能力详单校验(字段旧名 model 别名兼容)', (
);
});
- it('embed 类目未知动作 / 空数组 → 拒', () => {
- expect(validateGhostManifest(chipWithModel({ embed: ['image'] })).ok).toBe(false);
- expect(validateGhostManifest(chipWithModel({ embed: ['vector'] })).ok).toBe(false);
+ it('embed 保留未知动作,空数组仍拒绝', () => {
+ expect(validateGhostManifest(chipWithModel({ embed: ['image'] })).ok).toBe(true);
+ expect(validateGhostManifest(chipWithModel({ embed: ['vector'] })).ok).toBe(true);
expect(validateGhostManifest(chipWithModel({ embed: [] })).ok).toBe(false);
});
- it('text 类目未知动作 / 空数组 → 拒;五类目可同时声明', () => {
- expect(validateGhostManifest(chipWithModel({ text: ['complete'] })).ok).toBe(false);
+ it('text 保留未知动作,空数组仍拒绝;五类目可同时声明', () => {
+ expect(validateGhostManifest(chipWithModel({ text: ['complete'] })).ok).toBe(true);
expect(validateGhostManifest(chipWithModel({ text: [] })).ok).toBe(false);
const v = validateGhostManifest(
chipWithModel({
@@ -2224,11 +2222,11 @@ describe('ghost · subscribe 订阅详单校验(卡槽①,2026-07-12)', () => {
if (ok.ok) expect(ok.manifest.subscribe).toEqual({ hooks: ['will-user-message'] });
});
- it('未知主题/钩子/空对象/空数组/无槽有详单一律拒', () => {
- expect(validateGhostManifest(withSub({ topics: ['messages'] })).ok).toBe(false);
+ it('保留未知主题和钩子,空对象/空数组/无槽有详单仍拒绝', () => {
+ expect(validateGhostManifest(withSub({ topics: ['messages'] })).ok).toBe(true);
expect(
validateGhostManifest(withSub({ hooks: ['will-tool-call'] }, { launch: 'resident' })).ok,
- ).toBe(false);
+ ).toBe(true);
expect(validateGhostManifest(withSub({})).ok).toBe(false);
expect(validateGhostManifest(withSub({ topics: [] })).ok).toBe(false);
expect(validateGhostManifest(withSub({ topics: ['turn', 'turn'] })).ok).toBe(false);
@@ -2444,19 +2442,17 @@ describe('ghost · cindy 详单 video 类目', () => {
expect(both.ok && both.manifest.cindy?.video).toEqual(['generate']);
});
- it('video 未知动作 / 空数组 / 重复动作 → 拒;错误话术带类目名', () => {
- const bad = validateGhostManifest(withCindy({ video: ['transcode'] }));
- expect(bad.ok).toBe(false);
- expect(!bad.ok && bad.reason).toContain('video');
+ it('video 保留未知动作,空数组和重复动作仍拒绝', () => {
+ const future = validateGhostManifest(withCindy({ video: ['transcode'] }));
+ expect(future).toMatchObject({ ok: true, manifest: { cindy: { video: ['transcode'] } } });
expect(validateGhostManifest(withCindy({ video: [] })).ok).toBe(false);
expect(validateGhostManifest(withCindy({ video: ['generate', 'generate'] })).ok).toBe(false);
});
- it('未知类目报错列出全部支持类目(image / video / media)', () => {
- const bad = validateGhostManifest(withCindy({ audio: ['generate'] }));
- expect(bad.ok).toBe(false);
- expect(!bad.ok && bad.reason).toContain('video');
- expect(!bad.ok && bad.reason).toContain('media');
+ it('未知类目保留但不生成权限', () => {
+ const future = validateGhostManifest(withCindy({ audio: ['generate'] }));
+ expect(future).toMatchObject({ ok: true, manifest: { cindy: { audio: ['generate'] } } });
+ if (future.ok) expect(ghostPermissionItems(future.manifest).filter((item) => item.kind === 'cindy')).toEqual([]);
});
// #784:寄存是唯一"不花钱就写用户媒体库"的能力,确认框必须单独列一行,
@@ -3985,7 +3981,7 @@ describe('ghost · 2026-07-23 通用能力四件套(session-context / pick / pre
expect(withPreview({ hosts: ['UPPER.example.com'] }).ok).toBe(false);
expect(withPreview({ hosts: ['a.com', 'b.com', 'c.com', 'd.com', 'e.com'] }).ok).toBe(false);
expect(withPreview({ hosts: ['a.example.com', 'a.example.com'] }).ok).toBe(false);
- expect(withPreview({ hosts: ['a.example.com'], extra: 1 }).ok).toBe(false);
+ expect(withPreview({ hosts: ['a.example.com'], extra: 1 }).ok).toBe(true);
});
it('main-view / session-context / pick / workspace / ios-simulator 槽可装入并生成权限项', () => {
@@ -4267,12 +4263,12 @@ describe('ghost · skill 槽(捆绑 Agent Skills,2026-07-25)', () => {
if (good.ok) expect(good.manifest.skill?.items).toEqual(goodItems);
});
- it('items 形状:空/超限/非对象/自造字段一律拒', () => {
+ it('items 形状:空/超限/非对象拒绝,未知字段保留', () => {
expect(withSkill({ items: [] }).ok).toBe(false);
expect(withSkill({}).ok).toBe(false);
- expect(withSkill({ items: goodItems, extra: 1 }).ok).toBe(false);
+ expect(withSkill({ items: goodItems, extra: 1 }).ok).toBe(true);
expect(withSkill({ items: ['skills/foo'] }).ok).toBe(false);
- expect(withSkill({ items: [{ ...goodItems[0], scope: 'global' }] }).ok).toBe(false);
+ expect(withSkill({ items: [{ ...goodItems[0], scope: 'global' }] }).ok).toBe(true);
const five = Array.from({ length: 5 }, (_, i) => ({
dir: `skills/s${i}`,
name: `s${i}`,
diff --git a/apps/desktop/src/shared/ghost.ts b/apps/desktop/src/shared/ghost.ts
index 09e188383d..799d8aa31c 100644
--- a/apps/desktop/src/shared/ghost.ts
+++ b/apps/desktop/src/shared/ghost.ts
@@ -432,7 +432,7 @@ export interface GhostPanelDecl {
* minimize =「最小化面板」(恢复入口由用户偏好决定为浮动气泡或左侧栏)。
* 标准头本体(标题条)恒由主机绘制、
* 不可关——可配置的只是系统按钮;'tab' 形态没有标准头,声明本字段拒装。
- * 未知键按规则 9 收词明确拒绝,新按钮上线时在这里扩键。
+ * 未知键保留为声明数据;当前宿主只读取已实现的按钮。
*/
systemButtons?: { maximize?: boolean; detach?: boolean; minimize?: boolean };
}
@@ -566,9 +566,8 @@ export interface GhostCindyNeeds {
/**
* 快问快答偏好模型(目录模型 id,如 "codex/gpt-5.5";须与 text 含 "oneshot"
* 成对)。主机能从当前供应商目录解析到(且用户未停用)就用它,解析不到按
- * 未声明处理;用户在详情页的钉档永远优先于本声明。注意:旧宿主会把含本
- * 字段的身份卡**整份拒装**(cindy 详单未知类目硬拒)——声明前确认目标
- * 用户群的主机版本。
+ * 未声明处理;用户在详情页的钉档永远优先于本声明。
+ * 未实现本字段的兼容宿主保留声明但不使用它;插件仍需处理旧宿主差异。
*/
oneshotModel?: string;
}
@@ -1882,7 +1881,9 @@ export function ghostPermissionItems(manifest: GhostManifest): GhostPermissionIt
const items: GhostPermissionItem[] = [];
for (const [category, actions] of Object.entries(manifest.cindy ?? {})) {
if (category === 'oneshotModel') continue; // 偏好模型是标量意图,不是能力键
- for (const action of actions ?? []) {
+ if (!Array.isArray(actions)) continue;
+ for (const action of actions) {
+ if (typeof action !== 'string') continue;
const cap = `${category}.${action}`;
const labelKey = GHOST_CINDY_PERM_LABEL[cap];
// 快问快答声明了偏好模型:说明行换带模型的版本(装入即知情,成本透明)。
@@ -1891,7 +1892,7 @@ export function ghostPermissionItems(manifest: GhostManifest): GhostPermissionIt
const detailKey = declaredOneshotModel
? 'cindyTextOneshotModelDetail'
: GHOST_CINDY_PERM_DETAIL[cap];
- // 未登记的能力键不该出现(validateGhostManifest 已拦),防御性跳过。
+ // 未知声明保留为数据;只有当前 Host 实现的能力才进入权限投影。
if (labelKey) {
items.push({
key: `cindy:${cap}`,
@@ -2886,6 +2887,11 @@ function isGhostManifestReservedRecordKey(value: string): boolean {
return GHOST_MANIFEST_RESERVED_RECORD_KEYS.has(value);
}
+/** Preserve future declaration data without turning it into implemented Host permissions. */
+function unknownDeclarationFields(raw: Record<string, unknown>, known: readonly string[]): Record<string, unknown> {
+ return Object.fromEntries(Object.entries(raw).filter(([key]) => !known.includes(key)));
+}
+
function isPlainObject(v: unknown): v is Record<string, unknown> {
return typeof v === 'object' && v !== null && !Array.isArray(v);
}
@@ -3904,14 +3910,11 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
if (!isPlainObject(sb)) {
return { ok: false, reason: 'panel.systemButtons 必须是对象(如 { "maximize": false })' };
}
- // 收词明确拒绝未知键(规则 9):新系统按钮上线时在白名单里扩键。
+ // 未来按钮声明保留为数据,当前界面仅消费已实现的按钮。
const knownButtons = ['maximize', 'detach', 'minimize'];
for (const key of Object.keys(sb)) {
if (!knownButtons.includes(key)) {
- return {
- ok: false,
- reason: `panel.systemButtons 只认 ${knownButtons.join(' / ')},未知键:${key}`,
- };
+ continue;
}
if (typeof (sb as Record<string, unknown>)[key] !== 'boolean') {
return { ok: false, reason: `panel.systemButtons.${key} 必须是布尔值` };
@@ -3921,6 +3924,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
const detach = (sb as Record<string, unknown>).detach;
const minimize = (sb as Record<string, unknown>).minimize;
systemButtons = {
+ ...unknownDeclarationFields(sb, knownButtons),
...(typeof maximize === 'boolean' ? { maximize } : {}),
...(typeof detach === 'boolean' ? { detach } : {}),
...(typeof minimize === 'boolean' ? { minimize } : {}),
@@ -3962,6 +3966,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
}
}
panel = {
+ ...unknownDeclarationFields(p, ['title', 'position', 'html', 'minWidth', 'defaultFraction', 'systemButtons']),
...(p.title !== undefined ? { title: p.title as string } : {}),
...(position !== undefined ? { position } : {}),
html: p.html as string,
@@ -3976,15 +3981,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
if (!isPlainObject(raw.mainView)) {
return { ok: false, reason: 'mainView 必须是对象' };
}
- const unknownMainViewField = Object.keys(raw.mainView).find(
- (field) => field !== 'html' && field !== 'title' && field !== 'icon',
- );
- if (unknownMainViewField) {
- return {
- ok: false,
- reason: `mainView 含不允许的字段 ${JSON.stringify(unknownMainViewField)}`,
- };
- }
if (
raw.mainView.title !== undefined &&
(typeof raw.mainView.title !== 'string' ||
@@ -4009,6 +4005,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
mainView = {
+ ...unknownDeclarationFields(raw.mainView, ['html', 'title', 'icon']),
...(raw.mainView.title !== undefined ? { title: raw.mainView.title } : {}),
...(raw.mainView.icon !== undefined ? { icon: raw.mainView.icon as GhostMainViewIcon } : {}),
html: raw.mainView.html,
@@ -4088,15 +4085,12 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: '声明了 card 能力详单但 slots 未包含 "card"' };
}
const cardRaw = raw.card as Record<string, unknown>;
- const unknownCardField = Object.keys(cardRaw).find((key) => key !== 'externalLinks');
- if (unknownCardField) {
- return { ok: false, reason: `card 含不允许的字段 ${JSON.stringify(unknownCardField)}` };
- }
if (cardRaw.externalLinks !== undefined && typeof cardRaw.externalLinks !== 'boolean') {
return { ok: false, reason: 'card.externalLinks 必须是布尔值' };
}
- if (cardRaw.externalLinks === true) {
- card = { externalLinks: true };
+ const cardExtensions = unknownDeclarationFields(cardRaw, ['externalLinks']);
+ if (cardRaw.externalLinks === true || Object.keys(cardExtensions).length > 0) {
+ card = { ...cardExtensions, ...(cardRaw.externalLinks === true ? { externalLinks: true } : {}) };
}
}
@@ -4197,7 +4191,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
if (!slots.includes('cindy')) {
return { ok: false, reason: '声明了 cindy 能力详单但 slots 未包含 "cindy"' };
}
- cindy = {};
+ cindy = unknownDeclarationFields(cindyRaw, ['image', 'video', 'media', 'text', 'embed', 'search', 'oneshotModel']);
// oneshotModel(快问快答偏好模型)是标量键不是类目:先摘出,不进类目循环。
// 只验形态不验存在——目录随主机演进,声明式字段永不构成硬依赖。
const oneshotModelRaw = cindyRaw.oneshotModel;
@@ -4225,22 +4219,16 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
for (const [category, actionsRaw] of Object.entries(cindyRaw)) {
if (category === 'oneshotModel') continue;
- const allowed = actionTable[category];
- if (!allowed) {
- return {
- ok: false,
- reason: `cindy 含未知能力类目 ${JSON.stringify(category)}(当前支持:${Object.keys(actionTable).join(' / ')})`,
- };
- }
+ if (!Object.hasOwn(actionTable, category)) continue;
if (!Array.isArray(actionsRaw) || actionsRaw.length === 0) {
return { ok: false, reason: `cindy.${category} 必须是非空数组` };
}
const actions: string[] = [];
for (const a of actionsRaw) {
- if (typeof a !== 'string' || !allowed.includes(a)) {
+ if (typeof a !== 'string' || !GHOST_SLOT_NAME_RE.test(a)) {
return {
ok: false,
- reason: `cindy.${category} 含未知动作 ${JSON.stringify(a)}(可用:${allowed.join(' / ')})`,
+ reason: `cindy.${category} 动作必须是合法的能力标识: ${JSON.stringify(a)}`,
};
}
if (actions.includes(a)) {
@@ -4273,14 +4261,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
}
cindy.oneshotModel = (oneshotModelRaw as string).trim();
}
- if (
- cindy.image === undefined &&
- cindy.video === undefined &&
- cindy.media === undefined &&
- cindy.text === undefined &&
- cindy.embed === undefined &&
- cindy.search === undefined
- ) {
+ if (Object.keys(cindy).filter((key) => key !== 'oneshotModel').length === 0) {
return { ok: false, reason: 'cindy 能力详单不能是空对象' };
}
if (cindy.search?.includes('web') && (!slots.includes('tool') || tools === undefined)) {
@@ -4302,15 +4283,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: '声明了 agent 能力详单但 slots 未包含 "agent"' };
}
const agentRaw = raw.agent as Record<string, unknown>;
- const unknownAgentField = Object.keys(agentRaw).find(
- (key) => key !== 'background' && key !== 'errand' && key !== 'schedule',
- );
- if (unknownAgentField) {
- return {
- ok: false,
- reason: `agent 含不允许的字段 ${JSON.stringify(unknownAgentField)}`,
- };
- }
if (agentRaw.background !== undefined && typeof agentRaw.background !== 'boolean') {
return { ok: false, reason: 'agent.background 必须是布尔值' };
}
@@ -4320,7 +4292,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
if (agentRaw.schedule !== undefined && typeof agentRaw.schedule !== 'boolean') {
return { ok: false, reason: 'agent.schedule 必须是布尔值' };
}
- if (agentRaw.background !== true && agentRaw.errand !== true && agentRaw.schedule !== true) {
+ if (agentRaw.background !== true && agentRaw.errand !== true && agentRaw.schedule !== true && Object.keys(unknownDeclarationFields(agentRaw, ['background', 'errand', 'schedule'])).length === 0) {
return {
ok: false,
reason:
@@ -4328,14 +4300,14 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
agent = {
+ ...unknownDeclarationFields(agentRaw, ['background', 'errand', 'schedule']),
...(agentRaw.background === true ? { background: true } : {}),
...(agentRaw.errand === true ? { errand: true } : {}),
...(agentRaw.schedule === true ? { schedule: true } : {}),
};
}
- // node 槽详单:只收包内入口 + 固定 stdio 协议 + 生命周期。这里刻意采用
- // 字段白名单,command/args/shell/env 等任意命令启动面一律在装入前拒绝。
+ // Node 只执行受控入口与固定协议;未知扩展保留为数据,不传入进程启动参数。
let node: GhostNodeNeeds | undefined;
if (raw.node !== undefined) {
if (!isPlainObject(raw.node)) {
@@ -4345,22 +4317,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: '声明了 node 能力详单但 slots 未包含 "node"' };
}
const nodeRaw = raw.node as Record<string, unknown>;
- const allowedNodeFields = new Set([
- 'entry',
- 'protocol',
- 'lifecycle',
- 'idleTimeoutSeconds',
- 'entries',
- 'childSpawn',
- 'secretBindings',
- ]);
- const unknownNodeField = Object.keys(nodeRaw).find((key) => !allowedNodeFields.has(key));
- if (unknownNodeField) {
- return {
- ok: false,
- reason: `node 含不允许的字段 ${JSON.stringify(unknownNodeField)};不能声明 command/args/shell/env`,
- };
- }
if (!isSafeGhostRelativePath(nodeRaw.entry)) {
return { ok: false, reason: 'node.entry 必须是安装目录内的安全相对路径' };
}
@@ -4454,15 +4410,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: 'node.secretBindings 每项必须是对象' };
}
const binding = bindingRaw as Record<string, unknown>;
- const unknownBindingField = Object.keys(binding).find(
- (key) => !['key', 'label', 'methods', 'entry', 'hint', 'url', 'oauthSecret'].includes(key),
- );
- if (unknownBindingField) {
- return {
- ok: false,
- reason: `node.secretBindings[] 含不允许的字段 ${JSON.stringify(unknownBindingField)}`,
- };
- }
if (typeof binding.key === 'string' && isGhostManifestReservedRecordKey(binding.key)) {
return {
ok: false,
@@ -4577,6 +4524,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: 'node.secretBindings[].oauthSecret 必须是本插件 OAuth 凭证键' };
}
nodeSecretBindings.push({
+ ...unknownDeclarationFields(binding, ['key', 'label', 'methods', 'entry', 'hint', 'url', 'oauthSecret']),
...(binding.oauthSecret !== undefined ? { oauthSecret: binding.oauthSecret as string } : {}),
key: binding.key,
label: binding.label,
@@ -4588,6 +4536,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
}
}
node = {
+ ...unknownDeclarationFields(nodeRaw, ['entry', 'protocol', 'lifecycle', 'idleTimeoutSeconds', 'entries', 'childSpawn', 'secretBindings']),
entry: nodeRaw.entry,
protocol: nodeRaw.protocol as GhostNodeProtocol,
...(nodeRaw.lifecycle !== undefined
@@ -4617,10 +4566,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: '声明了 preview 详单但 slots 未包含 "preview"' };
}
const previewRaw = raw.preview as Record<string, unknown>;
- const unknownPreviewField = Object.keys(previewRaw).find((key) => key !== 'hosts');
- if (unknownPreviewField !== undefined) {
- return { ok: false, reason: `preview 含不允许的字段 ${JSON.stringify(unknownPreviewField)}` };
- }
if (!Array.isArray(previewRaw.hosts) || previewRaw.hosts.length === 0) {
return { ok: false, reason: 'preview.hosts 必须是非空数组(可打开预览的域名白名单)' };
}
@@ -4640,7 +4585,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
}
seenPreviewHosts.add(host);
}
- preview = { hosts: previewRaw.hosts as string[] };
+ preview = { ...unknownDeclarationFields(previewRaw, ['hosts']), hosts: previewRaw.hosts as string[] };
}
if (slots.includes('preview') && preview === undefined) {
return {
@@ -4667,10 +4612,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: '声明了 skill 详单但 slots 未包含 "skill"' };
}
const skillRaw = raw.skill as Record<string, unknown>;
- const unknownSkillField = Object.keys(skillRaw).find((key) => key !== 'items');
- if (unknownSkillField !== undefined) {
- return { ok: false, reason: `skill 含不允许的字段 ${JSON.stringify(unknownSkillField)}` };
- }
if (!Array.isArray(skillRaw.items) || skillRaw.items.length === 0) {
return { ok: false, reason: 'skill.items 必须是非空数组(随包捆绑的技能清单)' };
}
@@ -4685,15 +4626,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: 'skill.items 每项必须是对象({ dir, name, description })' };
}
const itemRaw = item as Record<string, unknown>;
- const unknownItemField = Object.keys(itemRaw).find(
- (key) => key !== 'dir' && key !== 'name' && key !== 'description',
- );
- if (unknownItemField !== undefined) {
- return {
- ok: false,
- reason: `skill.items 条目含不允许的字段 ${JSON.stringify(unknownItemField)}`,
- };
- }
if (!isSafeGhostRelativePath(itemRaw.dir)) {
return {
ok: false,
@@ -4727,9 +4659,9 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: `skill.items 含重复 dir ${JSON.stringify(itemRaw.dir)}` };
}
seenSkillDirs.add(dirFold);
- skillItems.push({ dir: itemRaw.dir, name: itemRaw.name, description: itemRaw.description });
+ skillItems.push({ ...unknownDeclarationFields(itemRaw, ['dir', 'name', 'description']), dir: itemRaw.dir, name: itemRaw.name, description: itemRaw.description });
}
- skill = { items: skillItems };
+ skill = { ...unknownDeclarationFields(skillRaw, ['items']), items: skillItems };
}
if (slots.includes('skill') && skill === undefined) {
return { ok: false, reason: 'slots 声明了 "skill" 但缺少 skill 详单(items 技能清单必填)' };
@@ -4747,10 +4679,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
const manualRaw = raw.manual as Record<string, unknown>;
- const unknownManualField = Object.keys(manualRaw).find((key) => key !== 'items');
- if (unknownManualField !== undefined) {
- return { ok: false, reason: `manual 含不允许的字段 ${JSON.stringify(unknownManualField)}` };
- }
if (!Array.isArray(manualRaw.items) || manualRaw.items.length === 0) {
return { ok: false, reason: 'manual.items 必须是非空数组(随包手册索引)' };
}
@@ -4765,15 +4693,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: 'manual.items 每项必须是对象({ dir, name, description })' };
}
const itemRaw = item as Record<string, unknown>;
- const unknownItemField = Object.keys(itemRaw).find(
- (key) => key !== 'dir' && key !== 'name' && key !== 'description',
- );
- if (unknownItemField !== undefined) {
- return {
- ok: false,
- reason: `manual.items 条目含不允许的字段 ${JSON.stringify(unknownItemField)}`,
- };
- }
if (!isSafeGhostRelativePath(itemRaw.dir)) {
return {
ok: false,
@@ -4816,13 +4735,13 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: `manual.items 含重复 dir ${JSON.stringify(itemRaw.dir)}` };
}
seenManualDirs.add(dirFold);
- manualItems.push({
+ manualItems.push({ ...unknownDeclarationFields(itemRaw, ['dir', 'name', 'description']),
dir: itemRaw.dir,
name: itemRaw.name,
description: itemRaw.description,
});
}
- manual = { items: manualItems };
+ manual = { ...unknownDeclarationFields(manualRaw, ['items']), items: manualItems };
}
// 订阅槽详单(卡槽①):与 slots 含 'subscribe' 成对(有详单必有槽;有槽
@@ -4841,12 +4760,9 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
if (!slots.includes('subscribe')) {
return { ok: false, reason: '声明了 subscribe 订阅详单但 slots 未包含 "subscribe"' };
}
- subscribe = {};
const subRaw = raw.subscribe as Record<string, unknown>;
- for (const [field, allowed] of [
- ['topics', GHOST_SUBSCRIBE_TOPICS],
- ['hooks', GHOST_SUBSCRIBE_HOOKS],
- ] as const) {
+ subscribe = unknownDeclarationFields(subRaw, ['topics', 'hooks']);
+ for (const field of ['topics', 'hooks'] as const) {
const listRaw = subRaw[field];
if (listRaw === undefined) continue;
if (!Array.isArray(listRaw) || listRaw.length === 0) {
@@ -4854,10 +4770,10 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
}
const list: string[] = [];
for (const item of listRaw) {
- if (typeof item !== 'string' || !(allowed as readonly string[]).includes(item)) {
+ if (typeof item !== 'string' || !GHOST_SLOT_NAME_RE.test(item)) {
return {
ok: false,
- reason: `subscribe.${field} 含未知项 ${JSON.stringify(item)}(可用:${allowed.join(' / ')})`,
+ reason: `subscribe.${field} 必须包含合法的事件标识: ${JSON.stringify(item)}`,
};
}
if (list.includes(item)) {
@@ -4868,10 +4784,10 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
if (field === 'topics') subscribe.topics = list as GhostSubscribeTopic[];
else subscribe.hooks = list as GhostSubscribeHook[];
}
- if (subscribe.topics === undefined && subscribe.hooks === undefined) {
+ if (Object.keys(subscribe).length === 0) {
return { ok: false, reason: 'subscribe 订阅详单不能是空对象' };
}
- if (subscribe.hooks !== undefined && raw.launch !== 'resident') {
+ if (subscribe.hooks?.some((hook) => (GHOST_SUBSCRIBE_HOOKS as readonly string[]).includes(hook)) && raw.launch !== 'resident') {
return {
ok: false,
reason:
@@ -5802,13 +5718,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
// setup 就绪声明:引用必须指向已声明的凭证/连接(悬空引用在装包期拒,
// 不留到运行期才发现作者写错);kv 引用要求 settingsHtml(没有设置页
// 没人填参数);Host 派生源没有用户配置动作,引用它属结构性误解,直接拒装。
- for (const binding of node?.secretBindings ?? []) {
- if (binding.oauthSecret === undefined) continue;
- const source = network?.secrets?.find((secret) => secret.key === binding.oauthSecret);
- if (source?.source !== 'oauth' || !source.oauth) {
- return { ok: false, reason: 'node.secretBindings[].oauthSecret 必须引用本插件已声明的 OAuth 凭证' };
- }
- }
+ // OAuth source resolution belongs to the runtime; declaration acceptance grants no credentials.
let setup: GhostSetupDecl | undefined;
if (raw.setup !== undefined) {
if (!isPlainObject(raw.setup)) {
diff --git a/docs/dev-rules/credentials-and-local-storage.md b/docs/dev-rules/credentials-and-local-storage.md
index 47b6820af2..a9e2111725 100644
--- a/docs/dev-rules/credentials-and-local-storage.md
+++ b/docs/dev-rules/credentials-and-local-storage.md
@@ -21,7 +21,9 @@
`safeStorage` 边界。不要新增自定义明文凭证文件,也不要把秘密下放给 Renderer、插件
或不受信任页面。
- 可信 Node Worker 的显式例外:`node.secretBindings[].oauthSecret` 只能引用本插件
- 已声明的 OAuth key。Host 根据本次 `authAccount`(省略时为默认账号)刷新并注入
+ 已声明的 OAuth key;这是调用时的凭证解析边界,不是发布或安装的能力支持门禁。
+ 引用尚不可用时保留声明,在调用时返回不支持/配置错误,不读取其他插件凭证。
+ Host 根据本次 `authAccount` 刷新并注入
短期 access token;不得注入 refresh token、返回 Renderer/Agent、写日志或落盘。
Worker 启动第三方 CLI 时仅用该次子进程环境传递,不修改全局环境或复用他账号配置。
这是高权限 Node 的受审查信任边界,不是系统沙箱或对恶意 Worker 的隔离保证。
diff --git a/docs/dev-rules/plugin-security-and-authoring.md b/docs/dev-rules/plugin-security-and-authoring.md
index 1f1f3c75fe..4f62a83877 100644
--- a/docs/dev-rules/plugin-security-and-authoring.md
+++ b/docs/dev-rules/plugin-security-and-authoring.md
@@ -59,7 +59,8 @@
`sessionContext`、`pick`、`workspace`、`iosSimulator`。不用就省略,写 `false` 是无效清单。
- `card: {}` 与 `agent: {}` 分别表示基础卡片能力和由真实用户点击触发 Agent 回合;
其它对象型能力必须至少包含一项真实能力,不能用空对象占位。
-- v3 未识别的顶层字段必须原样保留,但当前 Host 不展示、不授权、也不因此阻止安装。
+- v3 未识别的顶层字段,以及能力对象中的未知扩展字段、动作和订阅事件,必须原样保留,
+ 但当前 Host 不展示、不授权、也不因此阻止安装或发布。
未来 Host 识别该字段后,才按正常的能力展示和运行时守门链路启用。不能把
未知字段猜成现有权限,也不能让它意外获得能力。
- **Agent 在途调用不需要重复登记具体操作。** 插件工具是否执行由当前
@@ -477,9 +478,15 @@
- **manifest 扩展的降级兼容(#1283)。** v3 通过“未知顶层字段原样保留,但当前 Host
不展示、不授权、不阻止安装”解决向前兼容;能力一旦被 Host 支持,必须成为明确的直接字段
和权限映射。v2 仅保留输入兼容:未知但格式合法的 slot 允许安装、运行时不提供能力。
- 不得恢复独立的 Host slot 支持表或按名字猜测映射。`subscribe.topics` 等带具体
- 运行语义的子枚举仍严格校验;`schemaVersion > 3` 仍以 `GHOST_HOST_UNSUPPORTED` 拒绝,避免
+ 不得恢复独立的 Host slot 支持表或按名字猜测映射。能力动作和订阅事件只校验标识格式,
+ 不能以当前实现列表阻断声明;已知字段类型、安全路径、协议格式及运行时凭证边界仍校验。
+ `schemaVersion > 3` 仍以 `GHOST_HOST_UNSUPPORTED` 拒绝,避免
当前 Host 误读整体结构变化。已经发布的旧 Host 无法追改,降到 v3 改造前仍可能拒绝新清单。
+- **声明与实现进度解耦。** 插件开发不应等待客户端先注册每一项扩展;声明被接收不等于
+ API 已存在或获授权。插件必须检查所需接口是否存在,处理不支持响应,保留可用功能并对
+ 不可用部分给出升级提示。不得把权限拒绝、账号失效或网络故障当作“不支持”绕过。
+ `minCindyVersion` 用于版本兼容声明与分发选择,不是运行时能力探测:手动导入、
+ 旧版客户端或其它分发入口仍可能让不适配客户端安装插件,必须有运行时降级路径。
- `networkSlot.ts` 的 `as: 'media'` 不能只信任 Content-Type(GLB 常见
`application/octet-stream`),需要安全的 magic-byte/扩展名嗅探。
- SSH 远程场景必须让 `LiziMcpSessionContext` 携带 remote 标识;目录过户不得回退读取本机
diff --git a/docs/dev-rules/protocol-compatibility.md b/docs/dev-rules/protocol-compatibility.md
index aed4cc9481..e15a573360 100644
--- a/docs/dev-rules/protocol-compatibility.md
+++ b/docs/dev-rules/protocol-compatibility.md
@@ -224,9 +224,12 @@ X 快照有请求正文时,按原始 triggerMessageId 排除引用列表中的
- `mainView.icon` 是主视图入口的 Host 系统图标枚举,只作用于该入口;根级 `icon` 仍是插件
品牌图片协议。字段白名单、默认回退与完整枚举见 `FORGE_GUIDE` §4.20,不能用图片路径或
未声明别名绕过枚举。
-- 如果 Plugin Market/服务端仓会解析或严格校验新增的 manifest 字段/枚举,发布使用新能力
- 的插件前必须同步其本地 `plugin-protocol` 实现;这不要求 Cindy 客户端运行时依赖服务端,
- 也不改变两仓独立发布边界。
+- Plugin Market、仓库 CI 与 Desktop 不得用当前 Host 能力清单拒绝未知扩展字段、
+ 能力动作或订阅事件;未知声明保留为数据,由实际运行客户端决定是否支持。
+ 已知字段形状、安全路径和整体协议格式仍须校验。新增能力不要求发布入口先登记;
+ 只有改变既有字段结构或安全语义时才需要协调协议升级。
+- 插件必须检测接口并处理不支持响应,局部降级或提示升级。`minCindyVersion` 不能替代
+ 这些处理:手动导入、旧版或其它安装渠道仍可能将包交给不适配客户端。
## Review 清单
diff --git a/packages/plugin-protocol/src/__tests__/manifest.forward-compat.test.ts b/packages/plugin-protocol/src/__tests__/manifest.forward-compat.test.ts
new file mode 100644
index 0000000000..762fddf2f8
--- /dev/null
+++ b/packages/plugin-protocol/src/__tests__/manifest.forward-compat.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { validateGhostManifest } from '../manifest.js';
+
+const base = {
+ schemaVersion: 3, minCindyVersion: '0.1.0', id: 'future-declarations',
+ name: 'Future declarations', version: '1.0.0', entry: 'main.js',
+};
+const extension = { mode: 'future', options: [1, null, { enabled: true }] };
+
+describe('declaration forward compatibility is not Host authorization', () => {
+ it.each([
+ ['mainView', { html: 'view.html' }],
+ ['panel', { html: 'panel.html' }],
+ ['card', {}],
+ ['agent', {}],
+ ['node', { entry: 'node/worker.cjs', protocol: 'json-rpc-stdio' }],
+ ['preview', { hosts: ['example.test'] }],
+ ['skill', { items: [{ dir: 'skills/demo', name: 'demo', description: 'Demo', future: extension }] }],
+ ['manual', { items: [{ dir: 'manual/demo', name: 'demo', description: 'Demo', future: extension }] }],
+ ['subscribe', {}],
+ ])('preserves unknown %s fields through repeated normalization', (field, declaration) => {
+ const raw = { ...base, [field]: { ...declaration, future: extension } };
+ const result = validateGhostManifest(raw);
+ expect(result.ok, JSON.stringify(result)).toBe(true);
+ if (!result.ok) return;
+ expect(result.manifest[field]).toEqual(raw[field as keyof typeof raw]);
+ expect(validateGhostManifest(result.manifest)).toEqual(result);
+ });
+
+ it('preserves future categories, actions, topics and hooks without requiring known hook lifecycle', () => {
+ const raw = { ...base, cindy: { image: ['generate', 'future-action'], future: extension },
+ subscribe: { topics: ['future-topic'], hooks: ['future-hook'] } };
+ const result = validateGhostManifest(raw);
+ expect(result).toMatchObject({ ok: true, manifest: { cindy: raw.cindy, subscribe: raw.subscribe } });
+ });
+
+ it('keeps prototype-like extension keys as own data without changing object prototypes', () => {
+ const cindy = JSON.parse('{"__proto__":{"polluted":true},"constructor":{"future":true}}');
+ const result = validateGhostManifest({ ...base, cindy });
+ expect(result.ok).toBe(true);
+ if (!result.ok) return;
+ expect(Object.hasOwn(result.manifest.cindy!, '__proto__')).toBe(true);
+ expect(Object.getPrototypeOf(result.manifest.cindy!)).toBe(Object.prototype);
+ expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+ });
+
+ it('preserves unresolved OAuth and future binding metadata for runtime resolution', () => {
+ const binding = { key: 'access_token', label: 'Account', methods: ['run'],
+ oauthSecret: 'future_account', future: extension };
+ const result = validateGhostManifest({ ...base, settingsHtml: 'settings.html',
+ node: { entry: 'node/worker.cjs', protocol: 'json-rpc-stdio', secretBindings: [binding] } });
+ expect(result).toMatchObject({ ok: true, manifest: { node: { secretBindings: [binding] } } });
+ });
+
+ it.each([
+ { mainView: { html: '../escape.html', future: extension } },
+ { card: { externalLinks: 'yes', future: extension } },
+ { agent: { background: 'yes', future: extension } },
+ { node: { entry: '../worker.cjs', protocol: 'json-rpc-stdio', future: extension } },
+ { preview: { hosts: ['https://example.test/path'], future: extension } },
+ { skill: { items: [{ dir: '../escape', name: 'demo', description: 'Demo' }], future: extension } },
+ { cindy: { image: [42], future: extension } },
+ { cindy: { image: ['generate', 'generate'], future: extension } },
+ { subscribe: { topics: [42], future: extension } },
+ { subscribe: { hooks: ['will-user-message'], future: extension } },
+ ])('still rejects malformed known fields and unsafe paths: %j', (fields) => {
+ expect(validateGhostManifest({ ...base, ...fields }).ok).toBe(false);
+ });
+});
diff --git a/packages/plugin-protocol/src/__tests__/manifest.test.ts b/packages/plugin-protocol/src/__tests__/manifest.test.ts
index ff19a016a3..66a9665da0 100644
--- a/packages/plugin-protocol/src/__tests__/manifest.test.ts
+++ b/packages/plugin-protocol/src/__tests__/manifest.test.ts
@@ -1005,7 +1005,7 @@ describe('Ghost manifest contract', () => {
expect(validateGhostManifest(withoutMin)).toEqual({ ok: true, manifest: withoutMin });
});
- it('keeps v2 main-view paired and rejects unsafe or unknown mainView fields', () => {
+ it('keeps v2 main-view paired, rejects unsafe paths and preserves extension fields', () => {
const legacyBase = {
...validManifest,
minCindyVersion: '1.2.3',
@@ -1059,8 +1059,8 @@ describe('Ghost manifest contract', () => {
mainView: { html: 'main-view.html', position: 'left' },
}),
).toMatchObject({
- ok: false,
- reason: expect.stringContaining('不允许的字段'),
+ ok: true,
+ manifest: { mainView: { position: 'left' } },
});
});
@@ -1075,8 +1075,8 @@ describe('Ghost manifest contract', () => {
});
const withNode = (node: Record<string, unknown>) => validateGhostManifest({ ...base, node });
expect(withNode({ entry: 'node/a.cjs', protocol: 'mcp-stdio', command: 'sh' })).toMatchObject({
- ok: false,
- reason: expect.stringContaining('不能声明 command/args/shell/env'),
+ ok: true,
+ manifest: { node: { command: 'sh', entry: 'node/a.cjs', protocol: 'mcp-stdio' } },
});
expect(withNode({ entry: '../a.cjs', protocol: 'mcp-stdio' }).ok).toBe(false);
expect(withNode({ entry: 'index.js', protocol: 'mcp-stdio' })).toMatchObject({
@@ -1182,7 +1182,7 @@ describe('Ghost manifest contract', () => {
]);
});
- it('accepts only plugin-local declared OAuth references for Node bindings', () => {
+ it('preserves OAuth references for plugin-local runtime resolution', () => {
const manifest = {
...validManifest, settingsHtml: 'settings.html', slots: ['tool', 'network', 'node'],
network: { hosts: ['example.test'], secrets: [{
@@ -1199,7 +1199,7 @@ describe('Ghost manifest contract', () => {
if (result.ok) expect(result.manifest.node?.secretBindings?.[0]?.oauthSecret).toBe('mail_account');
const missing = structuredClone(manifest);
missing.node.secretBindings[0].oauthSecret = 'other_plugin';
- expect(validateGhostManifest(missing).ok).toBe(false);
+ expect(validateGhostManifest(missing).ok).toBe(true);
const staticSource = structuredClone(manifest);
staticSource.network.secrets[0].source = 'user';
expect(validateGhostManifest(staticSource).ok).toBe(false);
@@ -1330,7 +1330,6 @@ describe('Ghost manifest contract', () => {
{ ...binding, methods: ['mail/action', 'mail/action'] },
{ ...binding, hint: '' },
{ ...binding, url: 'http://mail.example.com/settings' },
- { ...binding, unexpected: true },
]) {
expect(
validateGhostManifest({
@@ -1415,18 +1414,18 @@ describe('Ghost manifest contract', () => {
ok: true,
manifest: { skill: { items: goodItems } },
});
- // items 形状:空/超限/非对象/自造字段一律拒
+ // 已知字段校验形状;扩展字段保留但不改变技能安装范围。
expect(validateGhostManifest({ ...base, skill: { items: [] } }).ok).toBe(false);
expect(validateGhostManifest({ ...base, skill: {} }).ok).toBe(false);
expect(validateGhostManifest({ ...base, skill: { items: goodItems, extra: 1 } }).ok).toBe(
- false,
+ true,
);
expect(
validateGhostManifest({
...base,
skill: { items: [{ ...goodItems[0], scope: 'global' }] },
}).ok,
- ).toBe(false);
+ ).toBe(true);
const five = Array.from({ length: 5 }, (_, i) => ({
dir: `skills/s${i}`,
name: `s${i}`,
@@ -1542,7 +1541,7 @@ describe('Ghost manifest contract', () => {
manual: { items: [], extra: true },
}).ok,
).toBe(false);
- expect(item({ extra: true }).ok).toBe(false);
+ expect(item({ extra: true }).ok).toBe(true);
const nine = Array.from({ length: 9 }, (_, index) => ({
dir: `manual/unit-${index}`,
name: `unit-${index}`,
@@ -1817,9 +1816,9 @@ describe('cindy 详单:media/text/embed/search 类目与 oneshotModel 校验', (
});
});
- it('text 与 embed 的动作集各归各(不接受串用)', () => {
- expect(validateGhostManifest({ ...base, cindy: { text: ['text'] } }).ok).toBe(false);
- expect(validateGhostManifest({ ...base, cindy: { embed: ['oneshot'] } }).ok).toBe(false);
+ it('保留当前类目尚未实现的动作,不替换或映射到其它类目', () => {
+ expect(validateGhostManifest({ ...base, cindy: { text: ['text'] } })).toMatchObject({ ok: true, manifest: { cindy: { text: ['text'] } } });
+ expect(validateGhostManifest({ ...base, cindy: { embed: ['oneshot'] } })).toMatchObject({ ok: true, manifest: { cindy: { embed: ['oneshot'] } } });
});
it('接受 search.web 并要求真实工具声明', () => {
@@ -1834,7 +1833,7 @@ describe('cindy 详单:media/text/embed/search 类目与 oneshotModel 校验', (
if (accepted.ok) expect(accepted.manifest.cindy).toEqual({ search: ['web'] });
expect(validateGhostManifest({ ...base, cindy: { search: ['web'] } }).ok).toBe(false);
- expect(validateGhostManifest({ ...manifest, cindy: { search: ['deep'] } }).ok).toBe(false);
+ expect(validateGhostManifest({ ...manifest, cindy: { search: ['deep'] } }).ok).toBe(true);
expect(validateGhostManifest({ ...manifest, cindy: { search: [] } }).ok).toBe(false);
expect(validateGhostManifest({ ...manifest, cindy: { search: ['web', 'web'] } }).ok).toBe(
false,
diff --git a/packages/plugin-protocol/src/manifest.ts b/packages/plugin-protocol/src/manifest.ts
index a32227ca9e..5ac6afa645 100644
--- a/packages/plugin-protocol/src/manifest.ts
+++ b/packages/plugin-protocol/src/manifest.ts
@@ -353,9 +353,8 @@ export interface GhostCindyNeeds {
/**
* 快问快答偏好模型(目录模型 id,如 "codex/gpt-5.5";须与 text 含 "oneshot"
* 成对)。主机能从当前供应商目录解析到(且用户未停用)就用它,解析不到按
- * 未声明处理;用户在详情页的钉档永远优先于本声明。注意:旧宿主会把含本
- * 字段的身份卡**整份拒装**(cindy 详单未知类目硬拒)——声明前确认目标
- * 用户群的主机版本。
+ * 未声明处理;用户在详情页的钉档永远优先于本声明。
+ * 未实现本字段的兼容宿主保留声明但不使用它;插件仍需处理旧宿主差异。
*/
oneshotModel?: string;
}
@@ -1133,6 +1132,11 @@ export function supportsCindyVersion(
return comparison !== null && comparison >= 0;
}
+/** Preserve future declaration data without turning it into implemented Host permissions. */
+function unknownDeclarationFields(raw: Record<string, unknown>, known: readonly string[]): Record<string, unknown> {
+ return Object.fromEntries(Object.entries(raw).filter(([key]) => !known.includes(key)));
+}
+
function isPlainObject(v: unknown): v is Record<string, unknown> {
return typeof v === 'object' && v !== null && !Array.isArray(v);
}
@@ -1567,6 +1571,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
}
}
panel = {
+ ...unknownDeclarationFields(p, ['title', 'position', 'html', 'minWidth', 'defaultFraction']),
...(p.title !== undefined ? { title: p.title as string } : {}),
...(p.position !== undefined ? { position: p.position as GhostPanelPosition } : {}),
html: p.html as string,
@@ -1580,15 +1585,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
if (!isPlainObject(raw.mainView)) {
return { ok: false, reason: 'mainView 必须是对象' };
}
- const unknownMainViewField = Object.keys(raw.mainView).find(
- (field) => field !== 'html' && field !== 'title' && field !== 'icon',
- );
- if (unknownMainViewField) {
- return {
- ok: false,
- reason: `mainView 含不允许的字段 ${JSON.stringify(unknownMainViewField)}`,
- };
- }
if (
raw.mainView.title !== undefined &&
(typeof raw.mainView.title !== 'string' ||
@@ -1616,6 +1612,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
mainView = {
+ ...unknownDeclarationFields(raw.mainView, ['html', 'title', 'icon']),
...(raw.mainView.title !== undefined ? { title: raw.mainView.title } : {}),
...(raw.mainView.icon !== undefined ? { icon: raw.mainView.icon as GhostMainViewIcon } : {}),
html: raw.mainView.html,
@@ -1716,18 +1713,12 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
const cardRaw = raw.card as Record<string, unknown>;
- const unknownCardField = Object.keys(cardRaw).find((key) => key !== 'externalLinks');
- if (unknownCardField) {
- return {
- ok: false,
- reason: `card 含不允许的字段 ${JSON.stringify(unknownCardField)}`,
- };
- }
if (cardRaw.externalLinks !== undefined && typeof cardRaw.externalLinks !== 'boolean') {
return { ok: false, reason: 'card.externalLinks 必须是布尔值' };
}
- if (cardRaw.externalLinks === true) {
- card = { externalLinks: true };
+ const cardExtensions = unknownDeclarationFields(cardRaw, ['externalLinks']);
+ if (cardRaw.externalLinks === true || Object.keys(cardExtensions).length > 0) {
+ card = { ...cardExtensions, ...(cardRaw.externalLinks === true ? { externalLinks: true } : {}) };
}
}
@@ -1815,7 +1806,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
reason: '声明了 cindy 能力详单但 slots 未包含 "cindy"',
};
}
- cindy = {};
+ cindy = unknownDeclarationFields(cindyRaw, ['image', 'video', 'media', 'text', 'embed', 'search', 'oneshotModel']);
// 类目 → 合法动作表(image / video / media / text / embed / search;动作集恰好
// 同名,但按类目查表,未来某类目动作分叉时这里天然承接)。
const actionTable: Record<string, readonly string[]> = {
@@ -1828,22 +1819,16 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
for (const [category, actionsRaw] of Object.entries(cindyRaw)) {
if (category === 'oneshotModel') continue; // 标量意图键,不是类目,单独校验
- const allowed = actionTable[category];
- if (!allowed) {
- return {
- ok: false,
- reason: `cindy 含未知能力类目 ${JSON.stringify(category)}(当前支持:${Object.keys(actionTable).join(' / ')})`,
- };
- }
+ if (!Object.hasOwn(actionTable, category)) continue;
if (!Array.isArray(actionsRaw) || actionsRaw.length === 0) {
return { ok: false, reason: `cindy.${category} 必须是非空数组` };
}
const actions: string[] = [];
for (const a of actionsRaw) {
- if (typeof a !== 'string' || !allowed.includes(a)) {
+ if (typeof a !== 'string' || !GHOST_SLOT_NAME_RE.test(a)) {
return {
ok: false,
- reason: `cindy.${category} 含未知动作 ${JSON.stringify(a)}(可用:${allowed.join(' / ')})`,
+ reason: `cindy.${category} 动作必须是合法的能力标识: ${JSON.stringify(a)}`,
};
}
if (actions.includes(a)) {
@@ -1866,14 +1851,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
reason: `cindy 能力类目 ${JSON.stringify(category)} 尚未接线(协议缺陷)`,
};
}
- if (
- cindy.image === undefined &&
- cindy.video === undefined &&
- cindy.media === undefined &&
- cindy.text === undefined &&
- cindy.embed === undefined &&
- cindy.search === undefined
- ) {
+ if (Object.keys(cindy).filter((key) => key !== 'oneshotModel').length === 0) {
return { ok: false, reason: 'cindy 能力详单不能是空对象' };
}
// oneshotModel(快问快答偏好模型)是标量意图键,不是类目:先摘出,不进类目循环。
@@ -1927,12 +1905,9 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
reason: '声明了 subscribe 订阅详单但 slots 未包含 "subscribe"',
};
}
- subscribe = {};
const subRaw = raw.subscribe as Record<string, unknown>;
- for (const [field, allowed] of [
- ['topics', GHOST_SUBSCRIBE_TOPICS],
- ['hooks', GHOST_SUBSCRIBE_HOOKS],
- ] as const) {
+ subscribe = unknownDeclarationFields(subRaw, ['topics', 'hooks']);
+ for (const field of ['topics', 'hooks'] as const) {
const listRaw = subRaw[field];
if (listRaw === undefined) continue;
if (!Array.isArray(listRaw) || listRaw.length === 0) {
@@ -1940,10 +1915,10 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
}
const list: string[] = [];
for (const item of listRaw) {
- if (typeof item !== 'string' || !(allowed as readonly string[]).includes(item)) {
+ if (typeof item !== 'string' || !GHOST_SLOT_NAME_RE.test(item)) {
return {
ok: false,
- reason: `subscribe.${field} 含未知项 ${JSON.stringify(item)}(可用:${allowed.join(' / ')})`,
+ reason: `subscribe.${field} 必须包含合法的事件标识: ${JSON.stringify(item)}`,
};
}
if (list.includes(item)) {
@@ -1957,10 +1932,10 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
if (field === 'topics') subscribe.topics = list as GhostSubscribeTopic[];
else subscribe.hooks = list as GhostSubscribeHook[];
}
- if (subscribe.topics === undefined && subscribe.hooks === undefined) {
+ if (Object.keys(subscribe).length === 0) {
return { ok: false, reason: 'subscribe 订阅详单不能是空对象' };
}
- if (subscribe.hooks !== undefined && raw.launch !== 'resident') {
+ if (subscribe.hooks?.some((hook) => (GHOST_SUBSCRIBE_HOOKS as readonly string[]).includes(hook)) && raw.launch !== 'resident') {
return {
ok: false,
reason:
@@ -2953,15 +2928,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
const agentRaw = raw.agent as Record<string, unknown>;
- const unknownAgentField = Object.keys(agentRaw).find(
- (key) => key !== 'background' && key !== 'errand' && key !== 'schedule',
- );
- if (unknownAgentField) {
- return {
- ok: false,
- reason: `agent 含不允许的字段 ${JSON.stringify(unknownAgentField)}`,
- };
- }
if (agentRaw.background !== undefined && typeof agentRaw.background !== 'boolean') {
return { ok: false, reason: 'agent.background 必须是布尔值' };
}
@@ -2971,7 +2937,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
if (agentRaw.schedule !== undefined && typeof agentRaw.schedule !== 'boolean') {
return { ok: false, reason: 'agent.schedule 必须是布尔值' };
}
- if (agentRaw.background !== true && agentRaw.errand !== true && agentRaw.schedule !== true) {
+ if (agentRaw.background !== true && agentRaw.errand !== true && agentRaw.schedule !== true && Object.keys(unknownDeclarationFields(agentRaw, ['background', 'errand', 'schedule'])).length === 0) {
return {
ok: false,
reason:
@@ -2979,14 +2945,14 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
agent = {
+ ...unknownDeclarationFields(agentRaw, ['background', 'errand', 'schedule']),
...(agentRaw.background === true ? { background: true } : {}),
...(agentRaw.errand === true ? { errand: true } : {}),
...(agentRaw.schedule === true ? { schedule: true } : {}),
};
}
- // node 槽详单:只收包内入口 + 固定 stdio 协议 + 生命周期。这里刻意采用
- // 字段白名单,command/args/shell/env 等任意命令启动面一律在装入前拒绝。
+ // Node 只执行受控入口与固定协议;未知扩展保留为数据,不传入进程启动参数。
let node: GhostNodeNeeds | undefined;
if (raw.node !== undefined) {
if (!isPlainObject(raw.node)) {
@@ -2999,22 +2965,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
const nodeRaw = raw.node as Record<string, unknown>;
- const allowedNodeFields = new Set([
- 'entry',
- 'protocol',
- 'lifecycle',
- 'idleTimeoutSeconds',
- 'entries',
- 'childSpawn',
- 'secretBindings',
- ]);
- const unknownNodeField = Object.keys(nodeRaw).find((key) => !allowedNodeFields.has(key));
- if (unknownNodeField) {
- return {
- ok: false,
- reason: `node 含不允许的字段 ${JSON.stringify(unknownNodeField)};不能声明 command/args/shell/env`,
- };
- }
if (!isSafeGhostRelativePath(nodeRaw.entry)) {
return { ok: false, reason: 'node.entry 必须是安装目录内的安全相对路径' };
}
@@ -3149,15 +3099,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: 'node.secretBindings 每项必须是对象' };
}
const binding = bindingRaw as Record<string, unknown>;
- const unknownBindingField = Object.keys(binding).find(
- (key) => !['key', 'label', 'methods', 'entry', 'hint', 'url', 'oauthSecret'].includes(key),
- );
- if (unknownBindingField) {
- return {
- ok: false,
- reason: `node.secretBindings[] 含不允许的字段 ${JSON.stringify(unknownBindingField)}`,
- };
- }
if (typeof binding.key !== 'string' || !/^[a-z][a-z0-9_]{0,31}$/.test(binding.key)) {
return {
ok: false,
@@ -3269,6 +3210,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: 'node.secretBindings[].oauthSecret 必须是本插件 OAuth 凭证键' };
}
nodeSecretBindings.push({
+ ...unknownDeclarationFields(binding, ['key', 'label', 'methods', 'entry', 'hint', 'url', 'oauthSecret']),
...(binding.oauthSecret !== undefined ? { oauthSecret: binding.oauthSecret as string } : {}),
key: binding.key,
label: binding.label,
@@ -3280,6 +3222,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
}
}
node = {
+ ...unknownDeclarationFields(nodeRaw, ['entry', 'protocol', 'lifecycle', 'idleTimeoutSeconds', 'entries', 'childSpawn', 'secretBindings']),
entry: nodeRaw.entry,
protocol: nodeRaw.protocol as GhostNodeProtocol,
...(nodeRaw.lifecycle !== undefined
@@ -3334,13 +3277,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
const previewRaw = raw.preview as Record<string, unknown>;
- const unknownPreviewField = Object.keys(previewRaw).find((key) => key !== 'hosts');
- if (unknownPreviewField !== undefined) {
- return {
- ok: false,
- reason: `preview 含不允许的字段 ${JSON.stringify(unknownPreviewField)}`,
- };
- }
if (!Array.isArray(previewRaw.hosts) || previewRaw.hosts.length === 0) {
return {
ok: false,
@@ -3372,7 +3308,7 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
}
seenPreviewHosts.add(host);
}
- preview = { hosts: previewRaw.hosts as string[] };
+ preview = { ...unknownDeclarationFields(previewRaw, ['hosts']), hosts: previewRaw.hosts as string[] };
}
if (slots.includes('preview') && preview === undefined) {
return {
@@ -3398,13 +3334,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
return { ok: false, reason: '声明了 skill 详单但 slots 未包含 "skill"' };
}
const skillRaw = raw.skill as Record<string, unknown>;
- const unknownSkillField = Object.keys(skillRaw).find((key) => key !== 'items');
- if (unknownSkillField !== undefined) {
- return {
- ok: false,
- reason: `skill 含不允许的字段 ${JSON.stringify(unknownSkillField)}`,
- };
- }
if (!Array.isArray(skillRaw.items) || skillRaw.items.length === 0) {
return {
ok: false,
@@ -3428,15 +3357,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
const itemRaw = item as Record<string, unknown>;
- const unknownItemField = Object.keys(itemRaw).find(
- (key) => key !== 'dir' && key !== 'name' && key !== 'description',
- );
- if (unknownItemField !== undefined) {
- return {
- ok: false,
- reason: `skill.items 条目含不允许的字段 ${JSON.stringify(unknownItemField)}`,
- };
- }
if (!isSafeGhostRelativePath(itemRaw.dir)) {
return {
ok: false,
@@ -3479,13 +3399,13 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
seenSkillDirs.add(dirFold);
- skillItems.push({
+ skillItems.push({ ...unknownDeclarationFields(itemRaw, ['dir', 'name', 'description']),
dir: itemRaw.dir,
name: itemRaw.name,
description: itemRaw.description,
});
}
- skill = { items: skillItems };
+ skill = { ...unknownDeclarationFields(skillRaw, ['items']), items: skillItems };
}
if (slots.includes('skill') && skill === undefined) {
return {
@@ -3506,13 +3426,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
const manualRaw = raw.manual as Record<string, unknown>;
- const unknownManualField = Object.keys(manualRaw).find((key) => key !== 'items');
- if (unknownManualField !== undefined) {
- return {
- ok: false,
- reason: `manual 含不允许的字段 ${JSON.stringify(unknownManualField)}`,
- };
- }
if (!Array.isArray(manualRaw.items) || manualRaw.items.length === 0) {
return { ok: false, reason: 'manual.items 必须是非空数组(随包手册索引)' };
}
@@ -3533,15 +3446,6 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
const itemRaw = item as Record<string, unknown>;
- const unknownItemField = Object.keys(itemRaw).find(
- (key) => key !== 'dir' && key !== 'name' && key !== 'description',
- );
- if (unknownItemField !== undefined) {
- return {
- ok: false,
- reason: `manual.items 条目含不允许的字段 ${JSON.stringify(unknownItemField)}`,
- };
- }
if (!isSafeGhostRelativePath(itemRaw.dir)) {
return {
ok: false,
@@ -3590,24 +3494,18 @@ export function validateGhostManifest(value: unknown): ManifestValidation {
};
}
seenManualDirs.add(dirFold);
- manualItems.push({
+ manualItems.push({ ...unknownDeclarationFields(itemRaw, ['dir', 'name', 'description']),
dir: itemRaw.dir,
name: itemRaw.name,
description: itemRaw.description,
});
}
- manual = { items: manualItems };
+ manual = { ...unknownDeclarationFields(manualRaw, ['items']), items: manualItems };
}
// setup 引用必须在交付边界就与同一份 manifest 的凭证、连接和设置入口对齐;
// 不能让服务端接受、Desktop 装入时才拒绝。
- for (const binding of node?.secretBindings ?? []) {
- if (binding.oauthSecret === undefined) continue;
- const source = network?.secrets?.find((secret) => secret.key === binding.oauthSecret);
- if (source?.source !== 'oauth' || !source.oauth) {
- return { ok: false, reason: 'node.secretBindings[].oauthSecret 必须引用本插件已声明的 OAuth 凭证' };
- }
- }
+ // OAuth source resolution belongs to the runtime; declaration acceptance grants no credentials.
let setup: GhostSetupDecl | undefined;
if (raw.setup !== undefined) {
if (!isPlainObject(raw.setup)) {