@zhin.js/agent-feature 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+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/README.md

@@ -0,0 +1,40 @@
+# @zhin.js/agent-feature
+
+下一代 Markdown Agent Feature。它从 `agents/<name>.agent.md` 构造 immutable Agent definition，不读取旧分形 `agent.ts`、`instructions.md` 或模块级 SubAgent registry。
+
+## 目录约定
+
+```text
+agents/
+├── planner.agent.md
+└── reviewer.agent.md
+```
+
+Agent 目录只允许一级、精确 `.agent.md` 后缀。`planner.agent.md` 的 local name 是 `planner`；child Plugin 的 qualified name 自动包含 Plugin instance path。
+
+## Markdown 契约
+
+```markdown
+# Planner
+
+Break the request into verifiable steps. Prefer reversible actions.
+```
+
+完整 Markdown 是 `instructions` SSOT。首个 heading 作为 description；没有 heading 时使用文件 identity。Feature 不绑定模型、system prompt 模板、tool policy 或 session store，这些属于 orchestrator adapter。
+
+## Projection
+
+`AgentIndex.list()` 返回全树 qualified descriptors；`visible(owner)` 和 `get(owner, name)` 使用 nearest-owner inheritance。不同 Plugin owner 的同名 Agent 不通过扫描顺序覆盖。
+
+Agent definition 是纯数据，没有 runtime disposer。单文件 HMR 只替换 Agent Slot，旧 turn lease 继续使用旧 instructions。
+
+## 依赖
+
+只依赖 Next Kernel 与 Feature Kit，不引入 AI SDK、模型 provider、Markdown/YAML parser 或数据库。
+
+## 验证
+
+```bash
+pnpm --filter @zhin.js/agent-feature test
+pnpm --filter @zhin.js/agent-feature build
+```

package/lib/agent-index.d.ts

@@ -0,0 +1,14 @@
+import type { CapabilitySlot, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { AgentDefinition } from './definition.js';
+export interface AgentDescriptor extends AgentDefinition {
+    readonly owner: PluginId;
+    readonly qualifiedName: string;
+    readonly source: string;
+}
+export declare class AgentIndex {
+    #private;
+    constructor(slots: readonly Readonly<CapabilitySlot<AgentDefinition>>[], snapshot: RuntimeSnapshot);
+    list(): readonly AgentDescriptor[];
+    visible(requester: PluginId): readonly AgentDescriptor[];
+    get(requester: PluginId, name: string): AgentDescriptor | undefined;
+}

package/lib/agent-index.js

@@ -0,0 +1,25 @@
+import { OwnerCapabilityIndex, } from '@zhin.js/feature-kit';
+export class AgentIndex {
+    #index;
+    constructor(slots, snapshot) {
+        this.#index = new OwnerCapabilityIndex(slots, snapshot);
+    }
+    list() {
+        return this.#index.entries().map(toDescriptor);
+    }
+    visible(requester) {
+        return this.#index.visible(requester).map(toDescriptor);
+    }
+    get(requester, name) {
+        const entry = this.#index.resolve(requester, name);
+        return entry ? toDescriptor(entry) : undefined;
+    }
+}
+function toDescriptor(entry) {
+    return Object.freeze({
+        ...entry.slot.definition,
+        owner: entry.owner,
+        qualifiedName: entry.qualifiedName,
+        source: entry.source,
+    });
+}

package/lib/definition.d.ts

@@ -0,0 +1,10 @@
+import type { ValidationContext } from '@zhin.js/feature-kit';
+declare const agentBrand: "zhin.agent/1";
+export interface AgentDefinition {
+    readonly $feature: typeof agentBrand;
+    readonly name: string;
+    readonly description: string;
+    readonly instructions: string;
+}
+export declare function parseAgentMarkdown(value: unknown, context: ValidationContext): AgentDefinition;
+export {};

package/lib/definition.js

@@ -0,0 +1,18 @@
+const agentBrand = 'zhin.agent/1';
+export function parseAgentMarkdown(value, context) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(`Agent ${context.source} must contain Markdown instructions`);
+    }
+    return Object.freeze({
+        $feature: agentBrand,
+        name: context.localName,
+        description: markdownSummary(value, context.localName),
+        instructions: value,
+    });
+}
+function markdownSummary(markdown, fallback) {
+    const line = markdown.split(/\r?\n/u)
+        .map((value) => value.trim())
+        .find((value) => /^#+\s+\S/u.test(value));
+    return line?.replace(/^#+\s*/u, '') ?? fallback;
+}

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export * from './agent-index.js';
+export * from './definition.js';
+export * from './provider.js';
+export { default } from './provider.js';

package/lib/index.js

@@ -0,0 +1,4 @@
+export * from './agent-index.js';
+export * from './definition.js';
+export * from './provider.js';
+export { default } from './provider.js';

package/lib/provider.d.ts

@@ -0,0 +1,5 @@
+import { AgentIndex } from './agent-index.js';
+export declare const agentFeatureId: import("@zhin.js/plugin-runtime").FeatureId;
+declare const agentFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").AgentDefinition, AgentIndex>>;
+export { agentFeature };
+export default agentFeature;

package/lib/provider.js

@@ -0,0 +1,44 @@
+import { join } from 'node:path';
+import { featureId } from '@zhin.js/plugin-runtime';
+import { defineFeatureProvider, } from '@zhin.js/feature-kit';
+import { AgentIndex } from './agent-index.js';
+import { parseAgentMarkdown } from './definition.js';
+export const agentFeatureId = featureId('zhin.agent');
+const agentFiles = {
+    id: 'agent-markdown',
+    async *discover(context) {
+        const directory = join(context.packageRoot, 'agents');
+        const entries = [...await context.host.list(directory)]
+            .sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            if (entry.kind !== 'file' || !isAgentFile(entry.name))
+                continue;
+            yield {
+                localName: entry.name.slice(0, -'.agent.md'.length),
+                source: join(directory, entry.name),
+                target: 'server',
+            };
+        }
+    },
+    load(source, context) {
+        return context.host.readText(source.source);
+    },
+};
+const agentFeature = defineFeatureProvider({
+    protocol: 1,
+    id: agentFeatureId,
+    authoring: {
+        conventions: [agentFiles],
+        validate: parseAgentMarkdown,
+    },
+    runtime: {
+        project(slots, context) {
+            return { value: new AgentIndex(slots, context.snapshot) };
+        },
+    },
+});
+function isAgentFile(value) {
+    return /^[a-z0-9][a-z0-9-]*\.agent\.md$/u.test(value);
+}
+export { agentFeature };
+export default agentFeature;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@zhin.js/agent-feature",
+  "version": "1.0.0",
+  "description": "Convention-based Markdown Agent Feature for Zhin Plugin Runtime",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@zhin.js/feature-kit": "1.0.0",
+    "@zhin.js/plugin-runtime": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "feature",
+    "entry": "./lib/provider.js",
+    "engine": "^1.0.0",
+    "featureApi": "1.0.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/im/agent-feature"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/im/agent-feature/tests"
+  }
+}

package/src/agent-index.ts

@@ -0,0 +1,45 @@
+import type { CapabilitySlot, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import {
+  OwnerCapabilityIndex,
+  type OwnerCapabilityEntry,
+} from '@zhin.js/feature-kit';
+import type { AgentDefinition } from './definition.js';
+
+export interface AgentDescriptor extends AgentDefinition {
+  readonly owner: PluginId;
+  readonly qualifiedName: string;
+  readonly source: string;
+}
+
+export class AgentIndex {
+  readonly #index: OwnerCapabilityIndex<AgentDefinition>;
+
+  constructor(
+    slots: readonly Readonly<CapabilitySlot<AgentDefinition>>[],
+    snapshot: RuntimeSnapshot,
+  ) {
+    this.#index = new OwnerCapabilityIndex(slots, snapshot);
+  }
+
+  list(): readonly AgentDescriptor[] {
+    return this.#index.entries().map(toDescriptor);
+  }
+
+  visible(requester: PluginId): readonly AgentDescriptor[] {
+    return this.#index.visible(requester).map(toDescriptor);
+  }
+
+  get(requester: PluginId, name: string): AgentDescriptor | undefined {
+    const entry = this.#index.resolve(requester, name);
+    return entry ? toDescriptor(entry) : undefined;
+  }
+}
+
+function toDescriptor(entry: OwnerCapabilityEntry<AgentDefinition>): AgentDescriptor {
+  return Object.freeze({
+    ...entry.slot.definition,
+    owner: entry.owner,
+    qualifiedName: entry.qualifiedName,
+    source: entry.source,
+  });
+}

package/src/definition.ts

@@ -0,0 +1,29 @@
+import type { ValidationContext } from '@zhin.js/feature-kit';
+
+const agentBrand = 'zhin.agent/1' as const;
+
+export interface AgentDefinition {
+  readonly $feature: typeof agentBrand;
+  readonly name: string;
+  readonly description: string;
+  readonly instructions: string;
+}
+
+export function parseAgentMarkdown(value: unknown, context: ValidationContext): AgentDefinition {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new TypeError(`Agent ${context.source} must contain Markdown instructions`);
+  }
+  return Object.freeze({
+    $feature: agentBrand,
+    name: context.localName,
+    description: markdownSummary(value, context.localName),
+    instructions: value,
+  });
+}
+
+function markdownSummary(markdown: string, fallback: string): string {
+  const line = markdown.split(/\r?\n/u)
+    .map((value) => value.trim())
+    .find((value) => /^#+\s+\S/u.test(value));
+  return line?.replace(/^#+\s*/u, '') ?? fallback;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './agent-index.js';
+export * from './definition.js';
+export * from './provider.js';
+export { default } from './provider.js';

package/src/provider.ts

@@ -0,0 +1,51 @@
+import { join } from 'node:path';
+import { featureId } from '@zhin.js/plugin-runtime';
+import {
+  defineFeatureProvider,
+  type SourceConvention,
+} from '@zhin.js/feature-kit';
+import { AgentIndex } from './agent-index.js';
+import { parseAgentMarkdown } from './definition.js';
+
+export const agentFeatureId = featureId('zhin.agent');
+
+const agentFiles: SourceConvention = {
+  id: 'agent-markdown',
+  async *discover(context) {
+    const directory = join(context.packageRoot, 'agents');
+    const entries = [...await context.host.list(directory)]
+      .sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      if (entry.kind !== 'file' || !isAgentFile(entry.name)) continue;
+      yield {
+        localName: entry.name.slice(0, -'.agent.md'.length),
+        source: join(directory, entry.name),
+        target: 'server',
+      };
+    }
+  },
+  load(source, context) {
+    return context.host.readText(source.source);
+  },
+};
+
+const agentFeature = defineFeatureProvider({
+  protocol: 1,
+  id: agentFeatureId,
+  authoring: {
+    conventions: [agentFiles],
+    validate: parseAgentMarkdown,
+  },
+  runtime: {
+    project(slots, context) {
+      return { value: new AgentIndex(slots, context.snapshot) };
+    },
+  },
+});
+
+function isAgentFile(value: string): boolean {
+  return /^[a-z0-9][a-z0-9-]*\.agent\.md$/u.test(value);
+}
+
+export { agentFeature };
+export default agentFeature;