git:20261023.83e1620 to git:20261026.a27804e

# AGENTS.md

## Scope

`dsh-agent-plugin-market` is a dual-face DSH plugin. It clones Git-backed

markets, exposes enabled skills to DSH, and registers authorized Codex hooks.

Treat the running DSH process and the browser UI as the integration target; this

repository is not a standalone web application.

## Repository Layout

- `lib/index.js`: Host composition root. Wires injected DSH services to the

market runtime, market service, hook manager, skills provider, startup update,

feature settings, model tools, tool guidance, and authenticated RPC routes.

- `lib/market-runtime.js`: Host runtime for DSH-home paths, configuration I/O,

Git command execution, market/plugin manifest parsing, and skill scanning.

- `lib/market-service.js`: Host lifecycle service for market Git operations,

plugin installation, skill state, hooks authorization, state views, and

startup auto-update.

- `lib/market-features.js`: Native DSH feature settings and optional tool/prompt

Fiber lifecycle; the live Config form is the `dsh-agent-plugin-market` profile entry.

- `lib/market-tools.js`: Host model tools for market state reads and workspace

plugin/skill override writes, with scoped restriction for home-path agents.

- `lib/market-config.js`: Pure configuration state transitions for markets,

installed plugins, skill switches, and related cleanup.

- `lib/codex-hook-manager.js`: Codex hook inspection, approval reconciliation,

generated bridge configuration, and hook Fiber lifecycle management.

- `lib/hook-reconcile-plan.js`: Pure desired-versus-active hook reconciliation

plan.

- `lib/codex-hooks.js`: Pure helpers for hook-source parsing, path validation,

stable fingerprints and storage keys, plus command-environment injection.

- `lib/client.js`: Browser plugin. It is plain JavaScript loaded by

`window.__ModuleLoader__`; split catalog models, shared controls, settings

section, and workspace dialog into internal functions/sections in this file;

use `require`, `React.createElement`, and no JSX, TypeScript, `import`, or

bundler-only features.

- `cordis.patch.yml`: Adds the package to the web profile composition.

- `package.json`: `@deepseek-ai/dsh-client-ui-primitives`,

`@deepseek-ai/dsh-home-paths`, and `@deepseek-ai/schemastery` are required

peer dependencies. `@deepseek-ai/dsh-hooks-codex` is an optional peer; when

absent, the UI shows the running-cohort profile `pnpm add` command for it and

`@deepseek-ai/dsh-hook-protocol`.

## DSH Upgrade and Compatibility Policy

- Implement features and API adaptations against the latest selected target DSH

version. Keep historical-version support limited, but support at least the

immediately preceding release when its APIs can support the plugin simply.

- Drop a historical version when its APIs no longer support the implementation

without complex compatibility code. Do not build elaborate bridges or parallel

implementations just to retain additional old versions; document the concrete

incompatibility and the resulting support boundary.

- Across a `0.x` release-line transition, normally retain only the final minor /

patch release of the preceding `0.x` line rather than every release in that line.

- If an older version's APIs remain fully compatible and need no adaptation, keep

declaring it supported regardless of its age; do not retire it merely because

it falls outside a rolling version window.

- E2E must cover the latest target and representative supported historical

versions, including the immediately preceding supported release and meaningful

API boundaries. Keep every test installation on its own coherent DSH cohort.

- Keep `engines.dsh`, dependency pins, CI coverage, runtime installation guidance,

and documentation consistent with the verified support set. Do not declare

unverified future versions compatible. Keep the plugin version plain SemVer,

without encoding the DSH target in a suffix.

## Development Rules

- Keep Host and Client responsibilities separate. Host code owns filesystem,

Git, persistent state, hooks, and RPC. Client code owns settings-page UI and

calls Host routes through the existing API helper.

- DSH development dependencies target `0.2.1-rc.3` (npm `next`;

`latest` targets `0.2.1-rc.2`). Pin each DSH package explicitly; individual

subpackage dist-tags can still point to older cohorts. `engines.dsh` currently

this support set.

The Host must inject both `connection` and `webServer`. The bundle patch must

also add `webServer` to the `connection` provider row while retaining

`webStartup`: Connection RPC getters retain the provider's shadow context.

Test with separate sibling Connection and WebServer provider Fibers; providing

the WebServer on the root Context hides this guard failure.

- Keep each CI smoke installation on one DSH release cohort with

`.github/pin-dsh.cjs` and a fresh step-local pnpm cache. Apply the hook to both

`dlx` and profile child installs; wildcard peers and framework patch ranges can

drift even when the CLI pins its DSH dependencies. Cross the supported runtime

versions with absent/present profile-local hooks dependencies, and verify actual

bridge availability through the authenticated market RPC instead of assuming

CLI dependencies are importable by profile plugins. Do not add the bridge to

`dsh.profile.bundles`; it has no bundle declaration. Retain Node downgrade tests

for bridge unavailability.

Revalidate the Cordis 4.0.5 / Loader 1.0.6 / Include 1.0.10 companion baseline

when upgrading DSH; newer framework APIs can break older app-boot consumers.

- Expose tool and prompt switches in the native plugin configuration's

`Agent 插件市场` / `功能` group, backed by DSH settings. Both preferences

default to enabled; disabling tools also suppresses their guidance, and home

sessions receive neither tools nor guidance. Preserve skill loading, hooks,

and market RPC independently of these switches. Own registrations and

settings subscriptions through the plugin Fiber and test live toggle disposal.

- Preserve hook safety invariants: hooks are disabled by default, the UI uses

double confirmation, approvals match the configuration fingerprint, hook

configuration file paths remain inside the plugin root, and command hooks

receive only `PLUGIN_ROOT`, `PLUGIN_DATA`, `CLAUDE_PLUGIN_ROOT`, and

`CLAUDE_PLUGIN_DATA`. Dispose hook Fibers when hooks are disabled, changed,

updated, or removed.

- Treat market content and hook configuration as untrusted input. Keep path

containment checks. Bind approvals to verified hook configuration

fingerprints, not market pull outcomes. Market pulls suspend hook Fibers while

Git mutates the checkout; reconciliation remounts matching approved

fingerprints, disposes mismatches, and clears approvals when the current hook

configuration disappears or becomes unusable.

- Use `@deepseek-ai/dsh-client-ui-primitives` before making a new UI control.

The page uses `Button`, `Input`, `Pill`, `Menu`, `Tooltip`, and

`DisclosureRow`. The native plugin configuration card follows the built-in

PluginCard layout and theme tokens; a bare `DisclosureRow` is a catalog row,

not a plugin configuration card. Use `--dsw-*` theme tokens for layout or any

missing-control adapter; never add fixed light/dark colors. The hooks switch

is a small native button adapter.

- Keep the settings section ID stable as `skills-and-hooks` unless the DSH

settings integration is intentionally migrated. The visible label is

`技能与挂钩`. Reuse the same MarketPage for the `agent-plugin-market` main

panel and settings section. Native `showInSidebar` defaults to enabled and

controls only the `sidebar.panellist` entry; hiding it must retain settings,

an already-open panel, skills, hooks, and model-facing feature lifetimes.

- Treat `lib/`, `package.json`, `cordis.patch.yml`, and applicable tests as the

source of truth for repository behavior. When behavior changes, update every

tracked Markdown document that describes it; do not describe Codex bridge

event support beyond the verified installed bridge/protocol contract.

- Use exclusive local debugging: link the Web profile to this repository root

and develop here. Do not use a separate Git worktree for debugging; switching

branches in the root checkout is allowed when needed.

- Do not start a replacement Vite server for the existing DSH GUI. Client

changes need a page refresh unless the DSH checkout's `pnpm run dev:web`

watcher is running; claim HMR only after verifying that watcher.

- Do not restart DSH autonomously or assume every Host/package edit requires

one. Verify the installed HMR contract and the actual reload trigger first:

profile recomposition can replace changed loaded files in installed or linked

plugins; module watching requires configured roots. Config Editor writes do

not themselves replace modules. If the runtime reports `restart-required` or

no supported reload path is active, ask the user to restart and confirm before

continuing runtime validation.

## Validation

Run the Node unit suite for core behavior before using the real DSH GUI for

end-to-end validation.

```bash

pnpm lint

pnpm test

pnpm typecheck

for file in lib/*.js test/*.test.js; do

node --check "$file" || exit

done

git diff --check

```

For UI, link this repository root into the target DSH web profile. For Host or

package changes, confirm the live schema/activation after a supported HMR reload;

only when a restart is needed, ask the user to restart and confirm first. Test

the existing GUI at `http://127.0.0.1:3080` with `agent-browser`. Do not use curl

as UI evidence. Check the settings entry, market controls,

disabled/enabled switch contrast, and both light and dark themes after visual

changes.

The Node suite covers configuration, runtime scanning, hook helpers,

reconciliation planning, and catalog-model behavior. For manual hook E2E

verification, create a disposable local Git market fixture under ignored

`test-repos/`, trigger a real DSH tool call, verify enabled delivery and disable

disposal, then update the market to check that unchanged approved fingerprints

remount and changed hook configurations require reapproval. Remove the

registered market and marker data after validation.

## Required Skill Routing

Read the named Harness skill before beginning the matching work:

- Cordis Host/Client, slots, services, or runtime plugin work: read

`cordis-plugin-development`.

- `cordis.patch.yml`, profile composition, or preset changes: read

`editing-cordis-compositions`.

- GUI testing or screenshots: read `agent-browser`, then run

`agent-browser skills get core`.

- DSH package APIs, hook protocol behavior, or version contracts: read

`contract-verification`.

- Dependency or workspace package-manager changes: read `pnpm`.

- Documentation changes: read `documentation`.

- Creating a commit: read `git-commit`.

## Git Delivery

Review `git status`, the exact diff, and staged contents before committing.

Do not commit `node_modules`, local DSH profile files, generated market data,

temporary hook fixtures, or screenshots. Use a focused Conventional Commit.

Push only when the user requests it; never force-push.