Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { isValidPluginNamespace } from '@cindy/plugin-protocol';
import { ghostInstallApprovalToken, ghostPartition, isValidGhostId, type GhostInstallApproval } from './ghost.js';
interface InstalledGhostIdentitySource {
manifest: { id: string };
dir?: string;
namespace?: string | null;
/** Registry instance key. Storage uses this and never a path-derived alias. */
instanceKey?: string;
namespaceState?: 'confirmed' | 'unconfirmed' | 'pending';
}
function isGhostIdValue(value: string): boolean {
return isValidGhostId(value);
}
/**
* A missing namespace is an old wire protocol state, not the root namespace.
* Once an installation is committed, callers must use a known identity with
* namespace === null for root or a non-empty namespace for an organization.
*/
type PluginNamespaceState =
| { kind: 'legacy' }
| { kind: 'known'; namespace: string | null };
export interface PluginLogicalIdentity {
namespace: string | null;
ghostId: string;
}
export function resolvePluginNamespaceState(raw: unknown): PluginNamespaceState {
if (typeof raw !== 'object' || raw === null || !hasDeliveryNamespace(raw)) {
return { kind: 'legacy' };
}
const namespace = (raw as { namespace?: unknown }).namespace;
if (namespace === null) return { kind: 'known', namespace: null };
if (!isValidPluginNamespace(namespace)) {
throw new Error('插件 namespace 不合法');
}
return { kind: 'known', namespace };
}
export function createPluginLogicalIdentity(
namespace: string | null,
ghostId: string,
): PluginLogicalIdentity {
if (namespace !== null && !isValidPluginNamespace(namespace)) {
throw new Error('插件 namespace 不合法');
}
if (!isValidGhostId(ghostId)) throw new Error('插件 ghostId 不合法');
return { namespace, ghostId };
}
export function hasDeliveryNamespace<T extends object>(
value: T,
): value is T & { namespace: string | null } {
return Object.prototype.hasOwnProperty.call(value, 'namespace');
}
/** Persist only a known identity. Missing stays legacy and is not written as root. */
export function deliveryNamespaceFields(
value: object,
): { namespace: string | null } | Record<string, never> {
return hasDeliveryNamespace(value) ? { namespace: value.namespace } : {};
}
export function knownDeliveryNamespacesDiffer(
left: object,
right: object,
): boolean {
return (
hasDeliveryNamespace(left) &&
hasDeliveryNamespace(right) &&
left.namespace !== right.namespace
);
}
export function sameDeliveryNamespaceState(left: object, right: object): boolean {
if (hasDeliveryNamespace(left) !== hasDeliveryNamespace(right)) return false;
if (!hasDeliveryNamespace(left) || !hasDeliveryNamespace(right)) return true;
return left.namespace === right.namespace;
}
export function downloadIdentityMatchesPlugin(
download: {
pluginId?: string;
releaseId?: string;
ghostId?: string;
namespace?: string | null;
},
plugin: {
id: string;
ghostId: string;
namespace?: string | null;
currentRelease: { id: string };
},
): boolean {
const pluginHasNamespace = hasDeliveryNamespace(plugin);
const downloadComplete =
download.pluginId !== undefined &&
download.releaseId !== undefined &&
download.ghostId !== undefined &&
hasDeliveryNamespace(download);
// A detail that already carries namespace must not accept a download that
// omits identity. Missing detail namespace stays compatible with old downloads.
if (pluginHasNamespace && !downloadComplete) return false;
const hasDownloadIdentity =
download.pluginId !== undefined ||
download.releaseId !== undefined ||
download.ghostId !== undefined ||
hasDeliveryNamespace(download);
if (!hasDownloadIdentity) return true;
return (
download.pluginId === plugin.id &&
download.releaseId === plugin.currentRelease.id &&
download.ghostId === plugin.ghostId &&
sameDeliveryNamespaceState(download, plugin)
);
}
/** Organization-scoped installs live under this reserved content/state root. */
export const PLUGIN_NS_INSTALL_ROOT = '_ns';
export const PLUGIN_ROOT_INSTALL_DIR = '_root';
export const PLUGIN_ROOT_INSTALL_ROOT = `${PLUGIN_NS_INSTALL_ROOT}/${PLUGIN_ROOT_INSTALL_DIR}`;
/** Archive ids are not namespaces and are not directory keys. */
const ARCHIVE_INSTANCE_KEY_RE = /^arch_[a-f0-9]{32}$/;
export function isArchiveInstanceKey(value: unknown): value is string {
return typeof value === 'string' && ARCHIVE_INSTANCE_KEY_RE.test(value);
}
export function isPluginInstanceKey(value: unknown): value is string {
return typeof value === 'string' && (
isValidGhostId(value) ||
isValidPluginStoragePart(value)
);
}
/** Posix-style relative id: `helper` or `_ns/acme/helper`. Safe for directories. */
export function pluginInstallRelId(identity: PluginLogicalIdentity): string {
if (identity.namespace === null) return identity.ghostId;
return `${PLUGIN_NS_INSTALL_ROOT}/${identity.namespace}/${identity.ghostId}`;
}
export function pluginNewInstallRelId(identity: PluginLogicalIdentity): string {
return `${PLUGIN_NS_INSTALL_ROOT}/${identity.namespace ?? PLUGIN_ROOT_INSTALL_DIR}/${identity.ghostId}`;
}
export function pluginInstallStoragePart(relId: string): string {
const identity = parsePluginInstallRelId(relId);
if (!identity) throw new Error('插件安装目录不合法');
return relId.startsWith(`${PLUGIN_ROOT_INSTALL_ROOT}/`)
? `${PLUGIN_ROOT_INSTALL_DIR}__${identity.ghostId}`
: pluginStoragePart(identity);
}
export function parsePluginInstallRelId(value: string): PluginLogicalIdentity | null {
if (isGhostIdValue(value)) return { namespace: null, ghostId: value };
const parts = value.split('/');
if (
parts.length === 3 &&
parts[0] === PLUGIN_NS_INSTALL_ROOT &&
(parts[1] === PLUGIN_ROOT_INSTALL_DIR || isValidPluginNamespace(parts[1])) &&
isValidGhostId(parts[2])
) {
return { namespace: parts[1] === PLUGIN_ROOT_INSTALL_DIR ? null : parts[1], ghostId: parts[2] };
}
return null;
}
export function isValidPluginInstallRelId(value: unknown): value is string {
return typeof value === 'string' && parsePluginInstallRelId(value) !== null;
}
/**
* Flat filesystem/vault/session id.
* Root stays `helper`; organization instances use `_ns__<namespace>__<ghostId>`.
* Double underscore is unambiguous because neither namespace nor ghostId contains `_`.
* Do not persist pluginInstallRelId (`/`) as a vault or file name.
*/
export function pluginStoragePart(identity: PluginLogicalIdentity): string {
if (identity.namespace === null) return identity.ghostId;
return `${PLUGIN_NS_INSTALL_ROOT}__${identity.namespace}__${identity.ghostId}`;
}
export function parsePluginStoragePart(value: string): PluginLogicalIdentity | null {
if (isGhostIdValue(value)) return { namespace: null, ghostId: value };
const rootPrefix = `${PLUGIN_ROOT_INSTALL_DIR}__`;
if (value.startsWith(rootPrefix) && isValidGhostId(value.slice(rootPrefix.length))) {
return { namespace: null, ghostId: value.slice(rootPrefix.length) };
}
const prefix = `${PLUGIN_NS_INSTALL_ROOT}__`;
if (!value.startsWith(prefix)) return null;
const rest = value.slice(prefix.length);
const sep = rest.indexOf('__');
if (sep <= 0 || sep + 2 >= rest.length) return null;
if (rest.indexOf('__', sep + 2) !== -1) return null;
const namespace = rest.slice(0, sep);
const ghostId = rest.slice(sep + 2);
try {
return createPluginLogicalIdentity(namespace, ghostId);
} catch {
return null;
}
}
export function isValidPluginStoragePart(value: unknown): value is string {
return typeof value === 'string' && parsePluginStoragePart(value) !== null;
}
/** Runtime / UI instance id: helper, _ns/acme/helper, or _ns__acme__helper. */
export function parsePluginInstanceId(value: string): PluginLogicalIdentity | null {
return parsePluginInstallRelId(value) ?? parsePluginStoragePart(value);
}
export function pluginInstanceInstallRelId(value: string): string | null {
if (parsePluginInstallRelId(value)) return value;
const identity = parsePluginStoragePart(value);
if (!identity) return null;
return value.startsWith(PLUGIN_ROOT_INSTALL_DIR + '__')
? pluginNewInstallRelId(identity) : pluginInstallRelId(identity);
}
/** Runtime / UI instance id: storage part or install rel id. */
export function isGhostInstanceId(value: unknown): value is string {
return typeof value === 'string' && parsePluginInstanceId(value) !== null;
}
export function installedGhostPhysicalRelId(ghost: InstalledGhostIdentitySource): string {
if (typeof ghost.dir === 'string') {
const fromDir = parseInstallRelIdFromDir(ghost.dir, ghost.manifest.id);
if (fromDir) return fromDir;
}
return pluginInstallRelId(installedGhostLogicalIdentity(ghost));
}
function parseInstallRelIdFromDir(dir: string, ghostId: string): string | null {
const normalized = dir.replace(/\\/g, '/').replace(/\/+$/, '');
const marker = `/${PLUGIN_NS_INSTALL_ROOT}/`;
const at = normalized.lastIndexOf(marker);
if (at >= 0) {
const rest = normalized.slice(at + marker.length);
const slash = rest.indexOf('/');
if (
slash > 0 &&
rest.slice(slash + 1) === ghostId &&
rest.indexOf('/', slash + 1) === -1
) {
return parsePluginInstallRelId(`${PLUGIN_NS_INSTALL_ROOT}/${rest}`)
? `${PLUGIN_NS_INSTALL_ROOT}/${rest}` : null;
}
}
if (normalized === ghostId || normalized.endsWith(`/${ghostId}`)) return ghostId;
return null;
}
export function installedGhostStoragePart(ghost: InstalledGhostIdentitySource): string {
if (ghost.instanceKey && isPluginInstanceKey(ghost.instanceKey)) return ghost.instanceKey;
return installedGhostPhysicalKeys(ghost).storagePart;
}
/** Renderer WebView attach claim. Main matches the physical instance key, not the logical one. */
export function installedGhostWebviewPartitionClaim(ghost: InstalledGhostIdentitySource): string {
return ghostPartition(installedGhostStoragePart(ghost));
}
/**
* Library / vault keys are storage parts. Prefer the installed ghost so an
* in-place stamp keeps the original directory; otherwise canonicalize an IPC
* instance id (`helper`, `_ns/acme/helper`, `_ns__acme__helper`).
*/
export function resolvePluginLibraryStorageKey(
instanceId: string,
ghost?: InstalledGhostIdentitySource | null,
): string | null {
if (ghost) return installedGhostStoragePart(ghost);
const relId = pluginInstanceInstallRelId(instanceId);
return relId ? pluginInstallStoragePart(relId) : null;
}
/**
* Directory and vault/runtime keys for an already-installed ghost.
*
* After an in-place namespace stamp the logical identity is namespaced, but the
* plugin still lives at the original root directory. Deriving keys from
* `installedGhostLogicalIdentity` stops/uninstalls `_ns/<ns>/<id>` while OAuth,
* KV and the runtime stay on `<id>`.
*/
export function installedGhostPhysicalKeys(
ghost: InstalledGhostIdentitySource,
): { relId: string; storagePart: string } {
const relId = installedGhostPhysicalRelId(ghost);
return { relId, storagePart: pluginInstallStoragePart(relId) };
}
export function installedGhostMutationTargetToken(
ghost: InstalledGhostIdentitySource & { dir: string; approval: GhostInstallApproval },
ownerScopeKey: string,
): string | null {
if (ghost.approval.state !== 'approved') return null;
return JSON.stringify([
ownerScopeKey,
ghost.dir,
installedGhostStoragePart(ghost),
ghostInstallApprovalToken(ghost.approval),
deliveryNamespaceFields(ghost),
]);
}
export function installedGhostLogicalIdentity(
ghost: InstalledGhostIdentitySource,
): PluginLogicalIdentity {
return createPluginLogicalIdentity(
hasDeliveryNamespace(ghost) ? ghost.namespace : null,
ghost.manifest.id,
);
}
export function findInstalledGhostByIdentity<T extends {
manifest: { id: string };
namespace?: string | null;
namespaceState?: 'confirmed' | 'unconfirmed' | 'pending';
}>(ghosts: readonly T[], identity: PluginLogicalIdentity): T | undefined {
const rel = pluginInstallRelId(identity);
return ghosts.find(
(ghost) => ghost.namespaceState !== 'pending' &&
pluginInstallRelId(installedGhostLogicalIdentity(ghost)) === rel,
);
}
/**
* Resolve a UI/IPC instance id to the installed ghost that owns that physical
* directory. Prefer storage-part equality so in-place migrated plugins keep
* their original directory key instead of a logical namespaced identity.
*/
/**
* Exact instance key or the content path of that same install.
* Does not fall through to a logical namespace alias.
*/
/**
* Local file import updates a root install of this ghost id, never an
* organization instance. Pending legacy directories have no namespace field
* and stay on the update path; Main still rejects an organization package.
* Confirmed or unconfirmed root uses namespace null. More than one match
* is not a root update.
*/
export function findInstalledRootGhostForFileImport<
T extends {
manifest: { id: string };
namespace?: string | null;
namespaceState?: 'confirmed' | 'unconfirmed' | 'pending';
},
>(ghosts: readonly T[], ghostId: string): T | null {
const matches = ghosts.filter((ghost) => {
if (ghost.manifest.id !== ghostId) return false;
if ((ghost.namespaceState === 'confirmed' || ghost.namespaceState === 'unconfirmed') &&
ghost.namespace === null) return true;
return ghost.namespaceState === 'pending' && !hasDeliveryNamespace(ghost);
});
return matches.length === 1 ? matches[0]! : null;
}
export function findInstalledGhostByInstanceId<T extends InstalledGhostIdentitySource>(
ghosts: readonly T[],
instanceId: string,
): T | undefined {
return ghosts.find((ghost) =>
ghost.instanceKey === instanceId ||
installedGhostStoragePart(ghost) === instanceId ||
installedGhostPhysicalRelId(ghost) === instanceId);
}
/**
* The only logical/instance resolver.
* An omitted namespace matches only when ghostId is unique.
* Anything that is not a bare ghost id is an instance key.
*/
export function resolvePluginInstanceQuery<T extends {
manifest: { id: string };
dir?: string;
namespace?: string | null;
namespaceState?: 'confirmed' | 'unconfirmed' | 'pending';
instanceKey?: string;
}>(
ghosts: readonly T[],
id: string,
namespace?: string | null,
): InstalledGhostIdentityResolve<T> {
if (namespace !== undefined) return resolveInstalledGhost(ghosts, id, namespace);
const byKey = findInstalledGhostByInstanceId(ghosts, id);
if (byKey) return { status: 'unique', ghost: byKey };
if (!isValidGhostId(id)) return { status: 'missing' };
return resolveInstalledGhost(ghosts, id);
}
export function findInstalledGhostForLocalUpdate<T extends {
manifest: { id: string };
dir?: string;
namespace?: string | null;
approval: GhostInstallApproval;
}>(ghosts: readonly T[], ghostId: string, instanceId: string, approvalToken: string): T | undefined {
if (!isValidPluginStoragePart(instanceId)) return undefined;
const ghost = findInstalledGhostByInstanceId(ghosts, instanceId);
return ghost?.manifest.id === ghostId && installedGhostStoragePart(ghost) === instanceId &&
ghostInstallApprovalToken(ghost.approval) === approvalToken ? ghost : undefined;
}
type InstalledGhostIdentityResolve<T> =
| { status: 'missing' }
| { status: 'unique'; ghost: T }
| { status: 'ambiguous'; candidates: T[] };
function listInstalledGhostsByGhostId<T extends { manifest: { id: string } }>(
ghosts: readonly T[],
ghostId: string,
): T[] {
return ghosts.filter((ghost) => ghost.manifest.id === ghostId);
}
/**
* `namespace === undefined` means the caller omitted it: unique ghostId is
* allowed, two or more same-name instances are ambiguous.
* `null` means root; a string means that organization.
*/
function isPendingLegacyGhost(ghost: {
namespaceState?: 'confirmed' | 'unconfirmed' | 'pending';
}): boolean {
return ghost.namespaceState === 'pending';
}
export function resolveInstalledGhost<
T extends {
manifest: { id: string };
namespace?: string | null;
namespaceState?: 'confirmed' | 'unconfirmed' | 'pending';
},
>(
ghosts: readonly T[],
ghostId: string,
namespace?: string | null,
): InstalledGhostIdentityResolve<T> {
if (namespace !== undefined) {
let identity;
try {
identity = createPluginLogicalIdentity(namespace, ghostId);
} catch {
return { status: 'missing' };
}
const ghost = findInstalledGhostByIdentity(ghosts, identity);
if (ghost) return { status: 'unique', ghost };
// A pending upgrade install has no confirmed namespace. namespace null is
// the only address in the ambiguity candidate list, and it must not be
// stolen from a real root install.
if (namespace === null) {
const sameName = ghosts.filter((candidate) => candidate.manifest.id === ghostId);
const pending = sameName.filter((candidate) =>
isPendingLegacyGhost(candidate) && !hasDeliveryNamespace(candidate));
// A lone pending install is not root. null selects it only when an
// ambiguity candidate labeled it that way beside another instance.
if (sameName.length > 1 && pending.length === 1) return { status: 'unique', ghost: pending[0]! };
if (sameName.length > 1 && pending.length > 1) return { status: 'ambiguous', candidates: pending };
}
return { status: 'missing' };
}
const candidates = listInstalledGhostsByGhostId(ghosts, ghostId);
if (candidates.length === 0) return { status: 'missing' };
if (candidates.length === 1) return { status: 'unique', ghost: candidates[0]! };
return { status: 'ambiguous', candidates };
}
/**
* Pick the installed instance a delivery/install target should update.
* Known namespace (including root null) matches that identity only.
* Omitted namespace is allowed only when ghostId is unique; two same-name
* instances must not silently share consent or an update.
*/
export function findInstalledGhostForDeliveryTarget<
T extends { manifest: { id: string }; namespace?: string | null },
>(ghosts: readonly T[], target: { ghostId: string; namespace?: string | null }): T | undefined {
if (hasDeliveryNamespace(target)) {
return findInstalledGhostByIdentity(
ghosts,
createPluginLogicalIdentity(target.namespace, target.ghostId),
);
}
const resolved = resolveInstalledGhost(ghosts, target.ghostId);
return resolved.status === 'unique' ? resolved.ghost : undefined;
}
function installedGhostNamespaceLabel(ghost: { namespace?: string | null }): string | null {
return hasDeliveryNamespace(ghost) ? ghost.namespace : null;
}
export function formatInstalledGhostAmbiguity(
ghostId: string,
candidates: readonly { namespace?: string | null }[],
): string {
const labels = candidates.map((candidate) => {
const namespace = installedGhostNamespaceLabel(candidate);
return namespace === null ? `root/${ghostId}` : `${namespace}/${ghostId}`;
});
return `插件 ${ghostId} 存在多个实例(${labels.join('、')})。请指定 namespace:null 表示 root,字符串表示企业 orgSlug。`;
}
/** JSON-safe ledger / map key. Root and legacy stay `ghostId`; org uses storage part. */
export function pluginLedgerRecordKey(plugin: {
ghostId: string;
namespace?: string | null;
}): string {
if (hasDeliveryNamespace(plugin) && plugin.namespace !== null) {
return pluginStoragePart(createPluginLogicalIdentity(plugin.namespace, plugin.ghostId));
}
return plugin.ghostId;
}
/**
* Same slash-command in a different known namespace may coexist.
* A legacy (unstamped) holder still conflicts with everyone.
*/
export function findConflictingGhostCommand<
T extends {
manifest: { id: string; command?: string };
dir?: string;
namespace?: string | null;
},
>(
ghosts: readonly T[],
command: string,
opts: {
incomingNamespace: string | null;
exemptPhysicalRelId?: string;
},
): T | undefined {
const fold = command.toLowerCase();
return ghosts.find((ghost) => {
if (ghost.manifest.command === undefined) return false;
if (ghost.manifest.command.toLowerCase() !== fold) return false;
if (opts.exemptPhysicalRelId !== undefined) {
const rel = installedGhostPhysicalRelId(ghost);
if (rel === opts.exemptPhysicalRelId) return false;
}
if (!hasDeliveryNamespace(ghost)) return true;
return ghost.namespace === opts.incomingNamespace;
});
}
export function listGhostsByCommand<
T extends { enabled?: boolean; manifest: { command?: string } },
>(ghosts: readonly T[], word: string, enabledOnly = true): T[] {
const fold = word.toLowerCase();
return ghosts.filter((ghost) => {
if (enabledOnly && ghost.enabled === false) return false;
return ghost.manifest.command !== undefined && ghost.manifest.command.toLowerCase() === fold;
});
}
/**
* A blocked instance registry must not invent a root install for an
* organization plugin, or rewrite an organization directory as root.
* Returns a user-facing reason, or null when the placement may proceed.
*/
export function organizationMarketPlacementError(input: {
scope?: string | null;
requestedNamespace: string | null;
installedRelId?: string | null;
}): string | null {
if (input.requestedNamespace !== null) return null;
const installed = input.installedRelId ? parsePluginInstallRelId(input.installedRelId) : null;
if (installed?.namespace) {
return '不能把企业插件更新成 root';
}
if (input.scope === 'organization') {
return '企业插件缺少 namespace,不能按 root 安装';
}
return null;
}
/** Market install and update both wait until the instance registry can be read. */
export function blockedInstanceRegistryMarketError(blocked: boolean): string | null {
return blocked ? '插件注册表暂不可用,市场安装和更新已暂停,请稍后重试' : null;
}