Merge remote-tracking branch 'origin/master' into codex/project-instruction-files

2026-07-11 23:02:24 +08:00
parent eee4f02108 7331720c8a
commit 1a3113ebb0
190 changed files with 12229 additions and 460 deletions
--- a/packages/core/agent-core/README.md
+++ b/packages/core/agent-core/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-agent-core

-The **providerless, executor-less, UI-less agent spine** as ONE Cordis bundle plugin. It loads the fixed set of services every harness agent needs and forwards the loop's `agents` list as its own config — so an app package composes a working agent by adding only a front door and the swappable backends.
+The **default executor-less, UI-less agent spine** as ONE Cordis bundle plugin. It loads the fixed set of services every harness agent needs, including the local skill provider, and forwards the loop's `agents` list as its own config — so an app package composes a working agent by adding only a front door and the swappable backends.

 This is the package to read to see **the whole plugin tree at once** and the canonical teaching map for the shared spine.

@@ -14,10 +14,13 @@ This is the package to read to see **the whole plugin tree at once** and the can
@deepseek-ai/dsh-session          event-sourced session log + store
@deepseek-ai/dsh-system-prompt    prompt-section + tool-schema assembly
@deepseek-ai/dsh-tools            tool registry + tools/pre-execute/post-execute
+@deepseek-ai/dsh-skill            skill provider registry
+@deepseek-ai/dsh-skill-local      local filesystem skill provider
@deepseek-ai/dsh-agent            agent registry + agent/* event vocabulary
@deepseek-ai/dsh-invariants       dev-mode event-contract assertions
@deepseek-ai/dsh-tool-bash        the model-facing bash/bash_output/bash_kill schemas
@deepseek-ai/dsh-workspace-context  AGENTS.md/CLAUDE.md workspace context loader
+@deepseek-ai/dsh-tool-skill       session-prefix skill catalog + model-facing loader schema
@deepseek-ai/dsh-agent-loop       THE concrete loop (gets the forwarded `agents`)
                                  (dsh-system-prompt gets the forwarded `persona`)
 ```
@@ -28,6 +31,7 @@ The spine is everything COMMON to every front door. The swappable and front-door

 - **the LLM adapter** — the bundle ships the abstract `llm` service; the leaf registers a concrete adapter on `ctx.llm` (`llm-deepseek`, `llm-pi-ai`, `llm-replay`).
 - **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl).
+- **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings.
 - **presentation + per-app infra** — the stdio UI / ACP bridge, a console logger, `hmr`. These form the coupled "front-door cluster" that the app packages ([`dsh-stdio-agent`](../../ui/stdio-agent/README.md), [`dsh-acp-agent`](../../ui/acp-agent/README.md)) bake in. `timer` is in the spine (common to both, stdout-silent); a console logger is NOT (it writes to stdout, which the ACP bridge reserves for JSON-RPC).

 This is the [interface/implementation/consumer seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md) raised to the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door.
@@ -36,11 +40,11 @@ This is the [interface/implementation/consumer seam](../../../docs/rfc/implement

 ```ts
 import type { Config } from '@deepseek-ai/dsh-agent-core'
-// { agents?, persona?, toolOrder?, workspaceContext? } — the schema intersects the child owners,
-// so validation and defaulting can never drift from the owners'.
+// { agents?, persona?, toolOrder?, tools?, skills?, workspaceContext? } — the schema intersects the owner schemas,
+// so validation and defaulting can never drift from the owners.
 ```

-The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — `persona` to `dsh-system-prompt` (default `''`), the deployment's persona section — `toolOrder` to `dsh-system-prompt` (absent — lexicographic), the explicit model-facing tool order — and `workspaceContext` to `dsh-workspace-context` (`false` disables automatic instruction-file loading). Forwarding is exactly why the owners can live in the shared spine even though the apps disagree on what to configure.
+The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; and `workspaceContext` to `dsh-workspace-context` (`false` disables automatic instruction-file loading). Workspace instructions are registered before the skill catalog so their session-prefix message renders first. Forwarding is exactly why the owners can live in the shared spine even though the apps disagree on what to configure.

 ## Why a code bundle, not a shared YAML include

--- a/packages/core/agent-core/package.json
+++ b/packages/core/agent-core/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@deepseek-ai/dsh-agent-core",
-  "description": "The providerless/executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + agents + invariants + tool-bash + workspace-context + agent-loop)",
+  "description": "The default executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + skills + agents + invariants + tool-bash + tool-skill + workspace-context + agent-loop)",
  "version": "0.0.1",
  "private": true,
  "type": "module",
@@ -29,8 +29,11 @@
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-workspace-context": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-skill": "^0.0.1",
+    "@deepseek-ai/dsh-skill-local": "^0.0.1",
    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
    "@deepseek-ai/dsh-tool-bash": "^0.0.1",
+    "@deepseek-ai/dsh-tool-skill": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
    "cordis": "^4.0.0-rc.6"
  },
@@ -43,8 +46,11 @@
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-workspace-context": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-skill": "workspace:^",
+    "@deepseek-ai/dsh-skill-local": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tool-skill": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
    "cordis": "^4.0.0-rc.6"
  },
--- a/packages/core/agent-core/src/index.ts
+++ b/packages/core/agent-core/src/index.ts
@@ -1,12 +1,13 @@
 /**
- * The providerless, executor-less, UI-less agent spine as ONE bundle plugin.
+ * The default executor-less, UI-less agent spine as ONE bundle plugin.
 *
 * Loads the fixed set of services every harness agent needs — `timer`, the LLM
 * service, the session store, system-prompt assembly, the tool registry, the
- * agent registry, the dev-mode invariants, the model-facing `bash` tool
- * schemas, workspace-context loading, and the concrete `agent-loop` — and
- * forwards the loop's `agents` list as its OWN config (default `[]`), so each
- * app supplies its own pre-created agents.
+ * skill registry plus local skill provider, the agent registry, the dev-mode
+ * invariants, the model-facing `bash` and `skill` tool schemas,
+ * workspace-context loading, and the concrete `agent-loop` — and forwards the
+ * loop's `agents` list as its OWN config (default `[]`), so each app supplies
+ * its own pre-created agents.
 *
 * It is deliberately NOT the whole app: the swappable choices stay OUTSIDE the
 * bundle, picked by whatever loads it.
@@ -19,6 +20,9 @@
 *    (a console logger, `hmr`) — these are the coupled "front-door cluster" the
 *    app packages ({@link @deepseek-ai/dsh-stdio-agent},
 *    {@link @deepseek-ai/dsh-acp-agent}) bake in, NOT the shared spine.
+ *  - additional SKILL PROVIDERS; the bundle ships the local filesystem provider
+ *    because local skills are default agent behavior, while embedded or remote
+ *    providers remain deployment choices.
 *
 * This is the interface/implementation/consumer seam at the composition level:
 * the bundle owns the shared spine, the leaf owns the backends, the app package
@@ -48,26 +52,38 @@ import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore from '@deepseek-ai/dsh-session'
 import SystemPrompt, { type Config as SystemPromptConfig } from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
+import SkillService, { type Config as SkillRegistryConfig } from '@deepseek-ai/dsh-skill'
+import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import * as invariants from '@deepseek-ai/dsh-invariants'
 import * as toolBash from '@deepseek-ai/dsh-tool-bash'
 import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
+import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
 import AgentLoop, { type Config as AgentLoopConfig } from '@deepseek-ai/dsh-agent-loop'

 export const name = 'agent-core'

+/** Skill bundle config forwarded to the registry, local provider, and model-facing consumer. */
+export interface SkillConfig {
+  /** Registry-level discovery cache settings. */
+  registry?: SkillRegistryConfig
+  /** Local filesystem skill provider settings. */
+  local?: SkillLocal.Config
+  /** Model-facing skill catalog and tool settings. */
+  tool?: toolSkill.Config
+}
+
 /**
 * Bundle config: each field forwarded verbatim to the child that owns it —
 * `agents` to the agent loop (an app that pre-creates no agents, like the ACP
 * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
 * plugin (the deployment's persona section and the explicit model-facing tool
 * order), the `tools` object to the tool registry (its presentation `mode`),
- * and `workspaceContext` to the workspace-context plugin. Every field is
- * optional INPUT here because each owner's schema supplies the default (`[]` /
- * `''` / absent — lexicographic / `native` / loader defaults); the schema is
- * the INTERSECTION of the owners' own schemas (the registry and workspace
- * loader nested under their bundle keys), so validation and defaulting cannot
- * drift from them.
+ * `skills` to the skill registry/local provider/tool consumer, and
+ * `workspaceContext` to the workspace-context plugin. Every field is optional
+ * INPUT here because each owner's schema supplies the default; the schema is
+ * the INTERSECTION of the owners' own schemas (with child schemas nested under
+ * their bundle keys), so validation and defaulting can never drift from them.
 */
 export interface Config {
  /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
@@ -80,16 +96,26 @@ export interface Config {
  tools?: ToolsConfig
  /** Workspace-context loader controls; set `false` for hermetic prompts. */
  workspaceContext?: workspaceContext.Config | false
+  /** Skill registry, local provider, and model-facing consumer config. */
+  skills?: SkillConfig
 }

+/** The skill config schema exported for app packages that forward `skills`. */
+export const SkillConfigSchema: z<SkillConfig> = z.object({
+  registry: SkillService.Config,
+  local: SkillLocal.Config,
+  tool: toolSkill.Config,
+})
+
 /** Intersect the owners' schemas so validation + defaulting stay identical. */
 export const Config = z.intersect([
  AgentLoop.Config,
  SystemPrompt.Config,
  z.object({
    tools: ToolRegistry.Config,
+    skills: SkillConfigSchema,
    workspaceContext: z.union([z.const(false), workspaceContext.Config]),
-  }) as unknown as z<Pick<Config, 'tools' | 'workspaceContext'>>,
+  }) as unknown as z<Pick<Config, 'tools' | 'skills' | 'workspaceContext'>>,
 ]) as unknown as z<Config>

 /**
@@ -117,11 +143,16 @@ export function apply(ctx: Context, config: Config): void {
    ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
  })
  ctx.plugin(ToolRegistry, config.tools ?? {})
+  ctx.plugin(SkillService, config.skills?.registry ?? {})
+  ctx.plugin(SkillLocal, config.skills?.local ?? {})
  ctx.plugin(AgentRegistry)
  ctx.plugin(invariants)
  ctx.plugin(toolBash)
  if (config.workspaceContext !== false) {
    ctx.plugin(workspaceContext, config.workspaceContext ?? {})
  }
+  // Both plugins prepend session-prefix messages. Registration order is the
+  // rendered order, so workspace instructions must precede the skill catalog.
+  ctx.plugin(toolSkill, config.skills?.tool ?? {})
  ctx.plugin(AgentLoop, { agents: config.agents ?? [] })
 }
--- a/packages/core/agent-core/tests/agent-core.spec.ts
+++ b/packages/core/agent-core/tests/agent-core.spec.ts
@@ -1,7 +1,7 @@
-import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises'
+import { describe, expect, it } from 'vitest'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
-import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
@@ -12,9 +12,17 @@ import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import { MockAdapter, textResponse } from '../../agent-loop/tests/mock-adapter.ts'
 import type { Message } from '@deepseek-ai/dsh-llm'

+async function composePrefix(ctx: Context, cwd: string): Promise<Message[]> {
+  const empty: Message[] = []
+  return await ctx.waterfall(
+    'agent/session-prefix', { session: { header: { cwd } } } as never,
+    empty, new AbortController().signal, () => Promise.resolve(empty),
+  )
+}
+
 /**
 * Unit coverage for the @deepseek-ai/dsh-agent-core bundle: mounting it brings
- * up the whole providerless spine in one `ctx.plugin`, and the forwarded
+ * up the whole default spine in one `ctx.plugin`, and the forwarded
 * `agents` config reaches the loop (default `[]`, or a pre-created agent).
 *
 * The bundle is exercised through `ctx.plugin(agentCore, …)` — the NAMESPACE
@@ -23,12 +31,50 @@ import type { Message } from '@deepseek-ai/dsh-llm'
 * bin smokes; here we assert the composition + config forwarding.
 */
 async function mount(config?: agentCore.Config): Promise<Context> {
+  const oldDshHome = process.env.DSH_HOME
+  const oldAgentsHome = process.env.DSH_AGENTS_HOME
+  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-home-'))
+  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-agents-'))
  const ctx = new Context()
-  await ctx.plugin(agentCore, config)
-  // The bundle mounts its children inside apply() (not awaited there); let their
-  // fibers settle so the spine services and any pre-created agent are ready.
-  await new Promise(resolve => setTimeout(resolve, 50))
-  return ctx
+  try {
+    await ctx.plugin(agentCore, config)
+    // The bundle mounts its children inside apply() (not awaited there); let their
+    // fibers settle so the spine services and any pre-created agent are ready.
+    await new Promise(resolve => setTimeout(resolve, 50))
+    return ctx
+  } finally {
+    if (oldDshHome === undefined) {
+      delete process.env.DSH_HOME
+    } else {
+      process.env.DSH_HOME = oldDshHome
+    }
+    if (oldAgentsHome === undefined) {
+      delete process.env.DSH_AGENTS_HOME
+    } else {
+      process.env.DSH_AGENTS_HOME = oldAgentsHome
+    }
+  }
+}
+
+async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
+  const oldDshHome = process.env.DSH_HOME
+  const oldAgentsHome = process.env.DSH_AGENTS_HOME
+  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-home-'))
+  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-agents-'))
+  try {
+    return await run()
+  } finally {
+    if (oldDshHome === undefined) {
+      delete process.env.DSH_HOME
+    } else {
+      process.env.DSH_HOME = oldDshHome
+    }
+    if (oldAgentsHome === undefined) {
+      delete process.env.DSH_AGENTS_HOME
+    } else {
+      process.env.DSH_AGENTS_HOME = oldAgentsHome
+    }
+  }
 }

 function waitForMainIdle(ctx: Context): Promise<void> {
@@ -47,7 +93,7 @@ function messageText(message: Message | undefined): string {
 }

 describe('dsh-agent-core bundle', () => {
-  it('brings up the full providerless spine', async () => {
+  it('brings up the full default spine', async () => {
    const ctx = await mount()
    // One service from each layer of the spine proves the children loaded.
    expect(ctx.get('timer')).toBeDefined()
@@ -55,11 +101,22 @@ describe('dsh-agent-core bundle', () => {
    expect(ctx.get('sessions')).toBeDefined()
    expect(ctx.get('systemPrompt')).toBeDefined()
    expect(ctx.get('tools')).toBeDefined()
+    expect(ctx.get('skills')).toBeDefined()
    expect(ctx.get('agents')).toBeDefined()
    expect(ctx.get('agentLoop')).toBeDefined()
    await ctx.fiber.dispose()
  })

+  it('includes the skill registry, local provider, and skill tool without builtin skills', async () => {
+    const ctx = await mount()
+
+    expect(ctx.skills).toBeDefined()
+    expect(ctx.tools.schemas().map(tool => tool.name)).toContain('skill')
+    expect(await ctx.skills.list()).toEqual([])
+
+    await ctx.fiber.dispose()
+  })
+
  it('defaults the agents list to empty (no pre-created agents)', async () => {
    const ctx = await mount()
    expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined()
@@ -148,6 +205,74 @@ describe('dsh-agent-core bundle', () => {
    }
  })

+  it('forwards skill config to the registry, local provider, and model-facing consumer', async () => {
+    const home = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-home-'))
+    const agentsHome = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-agents-'))
+    const custom = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-custom-'))
+    await mkdir(custom, { recursive: true })
+    await writeFile(join(custom, 'custom-skill.md'), '---\nname: custom-skill\ndescription: Custom skill\n---\n\nCustom body.\n')
+    const ctx = await mount({
+      agents: [],
+      skills: {
+        registry: { collectCacheMaxEntries: 4 },
+        local: {
+          dshHome: join(home, '.dsh'),
+          agentsHome: join(agentsHome, '.agents'),
+          customSkillDirs: [custom],
+        },
+        tool: { catalogDescriptionMaxLength: 6 },
+      },
+    })
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['custom-skill'])
+    expect(JSON.stringify(await composePrefix(ctx, '/tmp'))).toContain('- `custom-skill`: Cus...')
+    await ctx.fiber.dispose()
+  })
+
+  it('places workspace instructions before the skill catalog in the session prefix', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-agent-core-prefix-order-'))
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await writeFile(join(root, 'AGENTS.md'), 'workspace rule before skills')
+      const adapter = new MockAdapter([textResponse('ok')])
+      const ctx = await mount()
+      await ctx.plugin(LocalFileSystem, { cwd: '/' })
+      ctx.llm.registerAdapter(['mock'], adapter)
+      ctx.skills.register({
+        name: 'prefix-order-skill',
+        description: 'Skill catalog after workspace rules',
+        source: 'runtime',
+        content: 'body',
+      })
+      const handle = ctx.agents.create({
+        agentId: AgentId('main'),
+        sessionId: SessionId('prefix-order-session'),
+        meta: { cwd: root },
+        agentOptions: { model: 'mock' },
+      })
+
+      handle.agent.send([{ type: 'text', text: 'hi' }])
+      await waitForMainIdle(ctx)
+
+      expect(messageText(adapter.requests[0]?.messages[0])).toContain('workspace rule before skills')
+      expect(messageText(adapter.requests[0]?.messages[1])).toContain('prefix-order-skill')
+      await handle.dispose()
+      await ctx.fiber.dispose()
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it('uses the default skill config when apply is called directly without skills', async () => {
+    await withIsolatedSkillHomes(async () => {
+      const ctx = new Context()
+      agentCore.apply(ctx, { agents: [] })
+      await new Promise(resolve => setTimeout(resolve, 50))
+      expect(ctx.skills).toBeDefined()
+      expect(await ctx.skills.list()).toEqual([])
+      await ctx.fiber.dispose()
+    })
+  })
+
  it('forwards toolOrder to the system-prompt assembly', async () => {
    const ctx = await mount({ toolOrder: ['zulu', TOOL_ORDER_REST] })
    // The bundle's own bash tools pend on the absent `ctx.bash` executor in
@@ -161,7 +286,7 @@ describe('dsh-agent-core bundle', () => {
      })
    }
    const assembly = await ctx.get('systemPrompt')!.assemble()
-    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha'])
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'skill'])
    await ctx.fiber.dispose()
  })

--- a/packages/core/agent-core/tsconfig.json
+++ b/packages/core/agent-core/tsconfig.json
@@ -17,6 +17,9 @@
    {
      "path": "../../../vendor/timer"
    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
    {
      "path": "../../llm/llm"
    },
@@ -29,6 +32,15 @@
    {
      "path": "../../core/tools"
    },
+    {
+      "path": "../../skill/skill"
+    },
+    {
+      "path": "../../skill/skill-local"
+    },
+    {
+      "path": "../../skill/tool-skill"
+    },
    {
      "path": "../../core/agent"
    },