@deepmaid/maid-composer 0.0.0-stage → 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kenyonxu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# 空 patch 层:maid-composer 宿主全局挂载(消费 agent/created 等宿主钩子),不由 preset
+# 声明树承载;bundle 层仅承载包身份与面板元数据。空层以顶层 `[]` 承载(maid-veil 同款
+# 勘正:comment-only 会 parse 为 null,dsh-app-boot parsePatchList 即 throw)。
+[]

package/lib/index.d.ts

@@ -0,0 +1,117 @@
+//#region src/declaration.d.ts
+/**
+ * maid 差异层声明装载器(M3f §7.2):maid 内容目录的 agent.cordis.yml 仍是唯一内容源,
+ * 但 composer 只选择性读取 maid 差异四行(persona/anchor/gestures/veil)——标准工具树、
+ * 压缩、subagent 等行**不读取不挂载**(基底 preset 提供,修订 7:不复制上游工具树)。
+ * 相对路径(seeds map 值 / gesturesPath)以 maidDir 绝对化——composer 挂载不在 preset
+ * 组合目录,ctx.baseUrl 不是 maid 内容目录(批 2 通配①同款教训)。SOUL 不复制到任何
+ * 额外存储:persona 行 config 原样深拷贝交给 dsh-persona 插件消费。
+ */
+/** maid 差异层行名白名单(装载序 = maid 差异层的装配序:人格先行,三件殿后)。 */
+declare const MAID_DECLARATION_ROW_NAMES: readonly ["@deepseek-ai/dsh-persona", "@deepmaid/maid-anchor", "@deepmaid/maid-gestures", "@deepmaid/maid-veil"];
+interface MaidDeclarationRow {
+  /** 插件包名(name 是 cordis 装配键;id 仅供诊断透传,不参与装配)。 */
+  name: string;
+  id?: string;
+  config: Record<string, unknown>;
+}
+interface MaidDeclaration {
+  rows: MaidDeclarationRow[];
+  maidDir: string;
+}
+declare function loadMaidDeclaration(maidDir: string): MaidDeclaration;
+/**
+ * M3j 装载前校验(迎接/换模板事务在提交前调用):只读,不执行模型、不启动会话。
+ * 门槛:persona 行在场、includeRuntimeContext === false、prefix 非空且无 {{…}}
+ * prompt 变量(缓存纪律);seed/gestures 相对路径由 loader 绝对化(装载器语义)。
+ */
+declare function validateMaidDeclaration(maidDir: string): MaidDeclaration;
+//#endregion
+//#region src/compose.d.ts
+/**
+ * maid 差异层 agent scope 装配器(M3f §7):命中统一 maid 解析 → 在 agent scope 按声明
+ * 序挂载 persona/anchor/gestures/veil 四行(经 agent.ctx.plugin 复用官方/maid 插件
+ * apply,不复制注入逻辑);基底 preset 保留上游工具树(不读取不挂载)。
+ * 未命中 maid → 只 restrict maid 专属工具(memory_save/memory_search/curator_run),
+ * 绝不触碰官方 persona。maid 与 preset 首轮前双锁定:agent-preset/selected 重新 reconcile,
+ * 同 maid 幂等(模式切换不重挂不重置状态);maid 改绑先逆序 dispose 旧 scope。
+ * cron 装配缝 setup(agentCtx, maidId) 与 reconcile 走同一挂载路径(不建第二套逻辑)。
+ */
+/** composer 消费的 agent 最小面(dsh Agent 鸭子面:ctx 是 agent scope)。 */
+interface ComposerAgent {
+  id: string;
+  ctx: {
+    plugin(module: unknown, config?: unknown): {
+      dispose(): void | Promise<void>;
+    };
+    tools?: {
+      restrict?(opts: {
+        deny: string[];
+      }): void;
+    };
+  };
+}
+interface MaidComposerDeps {
+  /**
+   * 统一 maid 解析(pre-step 同款输入;session/event 面缺席时仅按绑定/路由解析)。
+   * baseOwnsDiffRows:投影基底 preset 即本 maid 自家 preset(legacy alias 形态)——
+   * 差异四行已由 preset 声明树提供,composer 叠加会同名 section 二次注册抛错,须跳过。
+   */
+  resolveFor(agent: ComposerAgent): {
+    maidId?: string;
+    source: string;
+    presetId?: string;
+    midSessionSwitch: boolean;
+    baseOwnsDiffRows?: boolean;
+  };
+  /** maid 声明装载(缓存策略由调用方定;composer 每次改绑现取,不缓存跨 maid)。 */
+  loadDeclaration(maidId: string): MaidDeclaration;
+  /** 行名 → 插件模块(官方 dsh-persona + 三个 maid 包;缺席 → fail-loud)。 */
+  rowPlugin(name: string): unknown;
+  /** 行模块异步预热闸门(reconcile/rebind/setup 先等它再挂载;缺席 = 调用方保证同步可解)。 */
+  prelude?: () => Promise<void>;
+  on(event: 'agent/created', listener: (payload: {
+    agent: ComposerAgent;
+    source?: unknown;
+  }) => void | Promise<void>): () => void;
+  on(event: 'agent-preset/selected', listener: (sessionId: string) => void | Promise<void>): () => void;
+  /** 启动时存量 agent 同步一次(CUA 同款:agents.list())。 */
+  agents?(): ComposerAgent[];
+  /** M3j:按 maidId 失效声明缓存(模板更换事务提交后调用;只影响后续新装载,不碰 scopes)。 */
+  invalidateDeclaration?(maidId: string): void;
+  warn?: (message: string) => void;
+}
+/** 无 maid 会话 deny 的 maid 专属工具(结构性隐藏优先;工具面自身另有领域错误兜底)。 */
+declare const NO_MAID_TOOL_DENY: readonly ["memory_save", "memory_search", "curator_run"];
+interface MaidComposer {
+  reconcile(agent: ComposerAgent): Promise<void>;
+  /** 首轮前 maid 改绑:dispose 旧 scope 后按新 maid 装配(cron/设置页显式路径)。 */
+  rebind(agent: ComposerAgent, maidId: string): Promise<void>;
+  /** cron 装配缝:basePreset 已由调用方 mount,这里只叠加 maid 差异层。 */
+  setup(agentCtx: ComposerAgent['ctx'], maidId: string): Promise<void>;
+  /** M3j:失效声明缓存(模板更换后新会话读新声明;既有 agent scope 不动)。 */
+  invalidate(maidId: string): void;
+  dispose(): void;
+}
+declare function createMaidComposer(deps: MaidComposerDeps): MaidComposer;
+//#endregion
+//#region src/index.d.ts
+declare const name = "maid-composer";
+declare const inject: string[];
+interface MaidComposerConfig {
+  /**
+   * maid 内容 roots(同 maid-identity roots 值);M3j 起缺席 → 托管默认
+   * ($DSH_HOME/deepmaid/maids,与 identity 缺省同值);显式 [](空数组)仍零钩子
+   * (出厂 A/B 车道消费该形态)。
+   */
+  maidRoots?: string[];
+}
+/**
+ * 宿主接线:maidIdentity(reflect 免 inject 直读,maid-cron 纪律)+ agent 生命周期钩子
+ * (agent/created、agent-preset/selected,CUA 同款)。rowPlugin 用动态 import 首挂载后缓存
+ * (懒加载避免无 maid 宿主白付四个包的装载成本);maidRoots 缺席 → one-shot warn + 零钩子
+ * (零行为改变出厂态)。
+ */
+declare function apply(ctx: any, config: MaidComposerConfig): void;
+//#endregion
+export { type ComposerAgent, MAID_DECLARATION_ROW_NAMES, type MaidComposer, MaidComposerConfig, type MaidComposerDeps, type MaidDeclaration, type MaidDeclarationRow, NO_MAID_TOOL_DENY, apply, createMaidComposer, inject, loadMaidDeclaration, name, validateMaidDeclaration };