@elinpf/dsh-ops-tool-environment 0.1.0

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+---
+title: "@elinpf/dsh-ops-tool-environment"
+description:
+  zh: "环境清单 — 只读扫描注册的 k8s 集群落盘 environment.yaml，附 environment 工具（overview/show/refresh）"
+  en: "Environment inventory — read-only scan of registered k8s clusters into environment.yaml, plus the environment tool (overview/show/refresh)"
+---

package/README.md

@@ -0,0 +1,50 @@
+# @elinpf/dsh-ops-tool-environment
+
+Environment inventory for DeepSeek Harness ops mode — a read-only, fully deterministic scanner that maps the k8s clusters registered in `ops-access` into `~/.dsh-ops/environment.yaml`, plus the model-facing `environment` tool the agent reads it through (spec `docs/specs/0004-environment-inventory.md`).
+
+## The `environment` tool
+
+Four actions: `overview` (all clusters, compact: middleware counts by type, unknown count, stale flag, scan time), `show` (one cluster: middleware instances, unknown bucket, relation edges), `refresh` (re-scan every registered k8s cluster now), `help` (full usage — progressive disclosure; the system prompt carries only a one-line pointer).
+
+- **Freshness** — reads re-scan when the inventory is missing or its oldest section is past the TTL (`ttlMinutes`, default 60); nothing scans at session start
+- **Read-only credentials** — refresh resolves k8s profiles without an agent identity, so the access gate's broker falls back to the ro tier
+- **Two mount rows** — realm topology splits the plugin: the tool entry (`.`) sits in the `ops-access-registry` group (needs `opsAccess`), the `./prompt` subpath plugin registers the one-line methodology section through `ops-prompts` and sits in the `ops-orchestration` group. Entry-local isolate realms are invisible across groups, so one row cannot see both services.
+
+## What it does
+
+For each registered k8s cluster, the scanner pulls workloads (deploy/sts/ds), Services, Ingresses, ConfigMaps, and Secret **metadata** from the k8s API via `kubectl`, classifies workloads against a middleware table, derives best-effort relation edges, and persists one section per cluster with a scan timestamp.
+
+- **Deterministic** — same cluster, same bytes; zero LLM involvement
+- **Freshness** — each section carries `scannedAt`; a failed refresh keeps the old section and marks it `stale: true`
+- **Unknown bucket** — unrecognized workloads stay listed with name and image
+- **Prometheus corroboration** — when a cluster has a discoverable Prometheus service (name contains `prometheus`, port 9090, `monitoring` namespace preferred), the scanner reads `/api/v1/targets` over a short-lived `kubectl port-forward` and attaches `monitoring: { up, down }` per workload. Any failure here degrades silently — the cluster section is still written and never marked stale for it
+- **Anomaly detection** — two generic-semantics detectors per section: `cross-namespace-ref` (a workload references a Service in another namespace) and `service-no-backend` (a Service has a selector but zero ready Endpoints addresses — Endpoints being k8s' authoritative backend answer). overview lists them in one section; show annotates entries in place
+- **User rules** — `~/.dsh-ops/environment-rules.yaml` appends/overrides classification rules
+
+## Security discipline
+
+- Secrets are fetched **metadata-only** (jsonpath of namespace/name) — `data` never enters the process
+- The kubeconfig path is scrubbed from every error before it can reach the inventory, logs, or the model
+- Only literal container env values are read; `valueFrom` contributes reference names only
+
+## Module map
+
+| Module | Role |
+|---|---|
+| `src/scanner.ts` | kubectl reads → `ClusterScan` (pure data, injectable exec, 30s timeout) |
+| `src/classify.ts` | image/chart/label → middleware type; built-in table + user rules file |
+| `src/relations.ts` | best-effort edges: `uses-service`, `fronts`, `uses-middleware`, `references-secret` |
+| `src/anomalies.ts` | rule-based anomaly detectors: `cross-namespace-ref`, `service-no-backend` (endpoints-based) |
+| `src/prometheus.ts` | Prometheus corroboration: service discovery, `kubectl port-forward` lifecycle (always reaped), targets parsing, workload matching |
+| `src/inventory.ts` | `environment.yaml` persistence, read API, refresh + stale logic |
+| `src/tool.ts` | the `environment` tool factory (actions, TTL gate, render); `createEnvironmentTool` takes injectable deps for tests |
+| `src/doctrine.ts` | single source of the tool description, one-line prompt, and help text |
+| `src/prompt.ts` | `./prompt` subpath plugin: registers the methodology line via `ops-prompts` |
+| `src/index.ts` | tool plugin entry (name/inject/Config/apply) + scanner-core re-exports |
+
+## Development
+
+```sh
+npm run build    # tsc → lib/
+npm test         # vitest
+```

package/README.zh.md

@@ -0,0 +1,50 @@
+# @elinpf/dsh-ops-tool-environment
+
+DeepSeek Harness 运维模式的环境清单 —— 只读、纯确定性的盘点器：遍历 `ops-access` 注册的 k8s 集群，盘出环境地图落盘为 `~/.dsh-ops/environment.yaml`；agent 经模型工具 `environment` 消费（spec 见 `docs/specs/0004-environment-inventory.md`）。
+
+## environment 工具
+
+四个动作：`overview`（各集群摘要：中间件分类计数、unknown 数、stale 标记、盘点时间）、`show`（单集群详情：中间件实例、unknown 桶、关联边）、`refresh`（立即重扫全部注册的 k8s 集群）、`help`（完整用法——渐进披露，系统提示词只放一句引导）。
+
+- **新鲜度** —— 清单缺失或最老段超 TTL（`ttlMinutes`，默认 60 分钟）时读操作先自动重扫；会话启动绝不扫描
+- **只读凭证** —— refresh 解析 k8s 档案不带 agent 身份，审计门 broker 无 agent 时回落 ro 档
+- **两行挂载** —— realm 拓扑拆分：工具入口（`.`）在 `ops-access-registry` 组（要 `opsAccess`），`./prompt` 子路径插件经 `ops-prompts` 注册那句提示词、挂在 `ops-orchestration` 组。entry-local isolate realm 跨组不可见，一行拿不到两个服务
+
+## 做什么
+
+对每个注册的 k8s 集群，经 `kubectl` 拉取工作负载（deploy/sts/ds）、Service、Ingress、ConfigMap 和 Secret **元数据**，按分类表识别中间件实例，尽力而为连关联边，按集群分段落盘并带盘点时间戳。
+
+- **确定性** —— 同一集群扫两次字节一致，零 LLM
+- **新鲜度** —— 每段带 `scannedAt`；刷新失败保留旧段并标 `stale: true`
+- **unknown 桶** —— 识别不出的工作负载照常列出名称与镜像
+- **Prometheus 印证** —— 集群里有可发现的 Prometheus service（名字含 `prometheus`、带 9090 端口、`monitoring` 命名空间优先）时，经短生命周期 `kubectl port-forward` 读 `/api/v1/targets`，给工作负载附 `monitoring: { up, down }`。此增强任何失败都静默降级——清单段照常写入，不标 stale
+- **异常标注** —— 每段跑两条通用语义检测器：`cross-namespace-ref`（工作负载引用别的命名空间的 Service）和 `service-no-backend`（Service 有 selector 但 Endpoints 零就绪地址——endpoints 是 k8s 自己的权威答案）。overview 单列一节，show 就地标注
+- **用户规则** —— `~/.dsh-ops/environment-rules.yaml` 可追加/覆盖分类规则
+
+## 安全纪律
+
+- Secret 只取 metadata（jsonpath 只选 namespace/name），`data` 不进进程
+- kubeconfig 路径在进入清单/日志/模型上下文前一律擦除为 `<kubeconfig>`
+- 容器 env 只读明文字面值；`valueFrom` 只记引用名
+
+## 模块划分
+
+| 模块 | 职责 |
+|---|---|
+| `src/scanner.ts` | kubectl 读取 → `ClusterScan`（纯数据，exec 可注入，30s 超时） |
+| `src/classify.ts` | 镜像/chart/label → 中间件类型；内置表 + 用户规则文件 |
+| `src/relations.ts` | 关联边：`uses-service`、`fronts`、`uses-middleware`、`references-secret` |
+| `src/anomalies.ts` | 异常检测器：`cross-namespace-ref`、`service-no-backend`（基于 endpoints） |
+| `src/prometheus.ts` | Prometheus 印证：service 发现、`kubectl port-forward` 生命周期（必然回收）、targets 解析、工作负载匹配 |
+| `src/inventory.ts` | `environment.yaml` 落盘、读接口、refresh + stale 逻辑 |
+| `src/tool.ts` | `environment` 工具工厂（动作、TTL 门、render）；`createEnvironmentTool` 依赖可注入便于测试 |
+| `src/doctrine.ts` | 工具描述、一句提示词、help 全文的唯一事实源 |
+| `src/prompt.ts` | `./prompt` 子路径插件：经 `ops-prompts` 注册提示词 |
+| `src/index.ts` | 工具插件入口（name/inject/Config/apply）+ 盘点器核心 re-export |
+
+## 开发
+
+```sh
+npm run build    # tsc → lib/
+npm test         # vitest
+```

package/cordis.patch.yml

@@ -0,0 +1 @@
+[]

package/lib/anomalies.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Anomaly detection over a scanned cluster (spec 0003 follow-up).
+ *
+ * Two deterministic detectors, both built on generic k8s semantics only —
+ * namespace string comparison and selector/endpoints agreement. Nothing
+ * here knows any environment's names; the same rules must flag (or stay
+ * silent on) any cluster shape.
+ *
+ * - `cross-namespace-ref` (info): a uses-service/uses-middleware edge whose
+ *   Service lives in a different namespace than the referencing workload.
+ *   Often legitimate (shared infrastructure), but a prime suspect when an
+ *   environment behaves like another one — the classic "e2e pointing at the
+ *   wrong namespace's database".
+ * - `service-no-backend` (warning): a Service with a pod selector whose
+ *   Endpoints object has ZERO ready addresses (or no Endpoints at all).
+ *   Endpoints are k8s' own authoritative answer to "does this Service have
+ *   backends" — preferred over inferring from fronts edges, which cannot
+ *   distinguish "selector matches nothing" from "pods exist but are not
+ *   ready / not in the scanned set".
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import type { Anomaly, RelationEdge, ScannedEndpoints, ScannedService } from './types.js';
+export interface DetectAnomaliesInput {
+    edges: RelationEdge[];
+    services: ScannedService[];
+    /** Undefined when the endpoints read failed — the no-backend detector then skips. */
+    endpoints?: ScannedEndpoints[];
+}
+/** All detected anomalies, deterministically ordered. Never throws. */
+export declare function detectAnomalies(input: DetectAnomaliesInput): Anomaly[];

package/lib/anomalies.js

@@ -0,0 +1,77 @@
+/**
+ * Anomaly detection over a scanned cluster (spec 0003 follow-up).
+ *
+ * Two deterministic detectors, both built on generic k8s semantics only —
+ * namespace string comparison and selector/endpoints agreement. Nothing
+ * here knows any environment's names; the same rules must flag (or stay
+ * silent on) any cluster shape.
+ *
+ * - `cross-namespace-ref` (info): a uses-service/uses-middleware edge whose
+ *   Service lives in a different namespace than the referencing workload.
+ *   Often legitimate (shared infrastructure), but a prime suspect when an
+ *   environment behaves like another one — the classic "e2e pointing at the
+ *   wrong namespace's database".
+ * - `service-no-backend` (warning): a Service with a pod selector whose
+ *   Endpoints object has ZERO ready addresses (or no Endpoints at all).
+ *   Endpoints are k8s' own authoritative answer to "does this Service have
+ *   backends" — preferred over inferring from fronts edges, which cannot
+ *   distinguish "selector matches nothing" from "pods exist but are not
+ *   ready / not in the scanned set".
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+function ref(kind, namespace, name) {
+    return { kind, namespace, name };
+}
+/** All detected anomalies, deterministically ordered. Never throws. */
+export function detectAnomalies(input) {
+    try {
+        const anomalies = [];
+        // ── Cross-namespace references ──────────────────────────────────────────
+        const seenCross = new Set();
+        for (const edge of input.edges) {
+            if (edge.kind !== 'uses-service' && edge.kind !== 'uses-middleware')
+                continue;
+            if (edge.from.namespace === edge.to.namespace)
+                continue;
+            const id = `${edge.from.namespace}/${edge.from.name}→${edge.to.namespace}/${edge.to.name}`;
+            if (seenCross.has(id))
+                continue;
+            seenCross.add(id);
+            anomalies.push({
+                kind: 'cross-namespace-ref',
+                severity: 'info',
+                ref: ref(edge.from.kind, edge.from.namespace, edge.from.name),
+                related: ref('Service', edge.to.namespace, edge.to.name),
+                message: `${edge.from.namespace}/${edge.from.name} references Service ${edge.to.namespace}/${edge.to.name} across namespaces`,
+            });
+        }
+        // ── Services with a selector but no ready backends ─────────────────────
+        // Only runs on real endpoints data; a failed read must not fabricate
+        // anomalies.
+        if (input.endpoints !== undefined) {
+            const endpointsByKey = new Map(input.endpoints.map(e => [`${e.namespace}/${e.name}`, e]));
+            for (const svc of input.services) {
+                if (svc.selector === null)
+                    continue; // selector-less (ExternalName/manual) has no backend contract
+                const ep = endpointsByKey.get(`${svc.namespace}/${svc.name}`);
+                if (ep !== undefined && ep.addresses > 0)
+                    continue;
+                anomalies.push({
+                    kind: 'service-no-backend',
+                    severity: 'warning',
+                    ref: ref('Service', svc.namespace, svc.name),
+                    message: `Service ${svc.namespace}/${svc.name} has a selector but no ready endpoints (no backend pods)`,
+                });
+            }
+        }
+        anomalies.sort((a, b) => a.kind.localeCompare(b.kind)
+            || a.ref.namespace.localeCompare(b.ref.namespace)
+            || a.ref.name.localeCompare(b.ref.name));
+        return anomalies;
+    }
+    catch {
+        // Best-effort by contract: detection must never break the inventory.
+        return [];
+    }
+}

package/lib/classify.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Middleware classification table.
+ *
+ * A workload is classified from three signal sources — image names, chart
+ * names, and labels — matched against an ordered rule list. First match wins.
+ * Built-in rules cover the common middleware of the ops environment; a user
+ * rules file (default `~/.dsh-ops/environment-rules.yaml`) can append or
+ * override them: user rules are consulted before built-in ones.
+ *
+ * Types are plain strings: a middleware name ('redis', 'mysql', ...),
+ * 'infra' for cluster plumbing (cert-manager, coredns, chaos-mesh, ...),
+ * or 'unknown' when nothing matches. 'unknown' is not an error — those
+ * workloads form the unknown bucket and stay visible.
+ *
+ * User rules file format:
+ *
+ *   rules:
+ *     - pattern: 'my-internal-mq'   # case-insensitive regex
+ *       type: mqtt
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import type { ScannedWorkload } from './types.js';
+/** One classification rule: a case-insensitive regex mapped to a type. */
+export interface ClassificationRule {
+    /** Regex source, matched case-insensitively against image/chart/label signals. */
+    pattern: string;
+    /** Type assigned on match ('redis', 'infra', a company-specific name, ...). */
+    type: string;
+}
+/** Signals a workload is classified on. */
+export interface ClassifyInput {
+    images: string[];
+    labels: Record<string, string>;
+    /** Workload name — a weak signal, only used by rules that want it. */
+    name?: string;
+}
+export declare const DEFAULT_USER_RULES_FILE = "~/.dsh-ops/environment-rules.yaml";
+/**
+ * Built-in table. Ordered: more specific patterns before generic ones so
+ * e.g. `redis-exporter` classifies as prometheus plumbing before `redis`
+ * would claim it. Infra components map to the 'infra' type, not a middleware.
+ */
+export declare const builtinRules: ClassificationRule[];
+export declare function expandHome(p: string): string;
+/**
+ * Load user classification rules. Missing or malformed file is not an
+ * error — the built-in table alone still works — so this always resolves
+ * to a (possibly empty) rule list. Entries without a string pattern/type
+ * are skipped.
+ */
+export declare function loadUserRules(file?: string): ClassificationRule[];
+/** Classify one signal set against an ordered rule list; first match wins. */
+export declare function classifySignals(input: ClassifyInput, rules: ClassificationRule[]): string;
+/**
+ * Classify a scanned workload. Loads built-in rules, then overlays the user
+ * rules file (user rules win ties — they are consulted first).
+ */
+export declare function classifyWorkload(workload: Pick<ScannedWorkload, 'images' | 'labels' | 'name'>, opts?: {
+    userRulesFile?: string;
+    extraRules?: ClassificationRule[];
+}): string;
+/** True for the middleware types worth surfacing as instances (not infra, not unknown). */
+export declare function isMiddlewareType(type: string): boolean;

package/lib/classify.js

@@ -0,0 +1,175 @@
+/**
+ * Middleware classification table.
+ *
+ * A workload is classified from three signal sources — image names, chart
+ * names, and labels — matched against an ordered rule list. First match wins.
+ * Built-in rules cover the common middleware of the ops environment; a user
+ * rules file (default `~/.dsh-ops/environment-rules.yaml`) can append or
+ * override them: user rules are consulted before built-in ones.
+ *
+ * Types are plain strings: a middleware name ('redis', 'mysql', ...),
+ * 'infra' for cluster plumbing (cert-manager, coredns, chaos-mesh, ...),
+ * or 'unknown' when nothing matches. 'unknown' is not an error — those
+ * workloads form the unknown bucket and stay visible.
+ *
+ * User rules file format:
+ *
+ *   rules:
+ *     - pattern: 'my-internal-mq'   # case-insensitive regex
+ *       type: mqtt
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import { readFileSync } from 'node:fs';
+import os from 'node:os';
+import { parse as parseYaml } from 'yaml';
+export const DEFAULT_USER_RULES_FILE = '~/.dsh-ops/environment-rules.yaml';
+/**
+ * Built-in table. Ordered: more specific patterns before generic ones so
+ * e.g. `redis-exporter` classifies as prometheus plumbing before `redis`
+ * would claim it. Infra components map to the 'infra' type, not a middleware.
+ */
+export const builtinRules = [
+    // ── exporters / sidecars before their middleware ────────────────────────
+    { pattern: 'redis[-_.]exporter', type: 'infra' },
+    { pattern: 'mysql[-_.]exporter', type: 'infra' },
+    { pattern: 'elasticsearch[-_.]exporter', type: 'infra' },
+    { pattern: 'kafka[-_.]exporter', type: 'infra' },
+    { pattern: 'mongodb[-_.]exporter', type: 'infra' },
+    { pattern: 'postgres[-_.]exporter', type: 'infra' },
+    { pattern: 'mysqld[-_.]exporter', type: 'infra' },
+    // ── middleware (spec 0003 list) ─────────────────────────────────────────
+    { pattern: 'nacos', type: 'nacos' },
+    { pattern: 'sentinel', type: 'sentinel' },
+    { pattern: 'seata', type: 'seata' },
+    { pattern: '\\bredis\\b', type: 'redis' },
+    { pattern: 'elasticsearch', type: 'elasticsearch' },
+    { pattern: '\\bkafka\\b', type: 'kafka' },
+    { pattern: '\\bmysql\\b', type: 'mysql' },
+    { pattern: '\\bmariadb\\b', type: 'mysql' },
+    { pattern: 'clickhouse', type: 'clickhouse' },
+    { pattern: '\\bminio\\b', type: 'minio' },
+    { pattern: '\\bmilvus\\b', type: 'milvus' },
+    { pattern: '\\bemqx\\b', type: 'mqtt' },
+    { pattern: 'mosquitto', type: 'mqtt' },
+    { pattern: 'hivemq', type: 'mqtt' },
+    { pattern: 'vernemq', type: 'mqtt' },
+    { pattern: '\\bmongo\\b', type: 'mongodb' },
+    { pattern: 'mongodb', type: 'mongodb' },
+    { pattern: '\\bpostgres\\b', type: 'postgres' },
+    { pattern: 'postgresql', type: 'postgres' },
+    // ── monitoring-suite members before the generic prometheus rule ─────────
+    { pattern: 'node[-_.]exporter', type: 'infra' },
+    { pattern: 'kube-state-metrics', type: 'infra' },
+    { pattern: 'prometheus-config-reloader', type: 'infra' },
+    { pattern: 'prometheus-operator', type: 'infra' },
+    { pattern: '\\bgrafana\\b', type: 'grafana' },
+    { pattern: '\\balertmanager\\b', type: 'alertmanager' },
+    { pattern: 'prometheus', type: 'prometheus' },
+    // common companions of the listed middleware
+    { pattern: '\\bzookeeper\\b', type: 'zookeeper' },
+    { pattern: '\\brabbitmq\\b', type: 'rabbitmq' },
+    { pattern: '\\bnats\\b', type: 'nats' },
+    { pattern: '\\bconsul\\b', type: 'consul' },
+    { pattern: '\\betcd\\b', type: 'etcd' },
+    // ── infra (cluster plumbing, not middleware) ────────────────────────────
+    { pattern: 'cert-manager', type: 'infra' },
+    { pattern: 'coredns', type: 'infra' },
+    { pattern: 'chaos-mesh', type: 'infra' },
+    { pattern: 'chaos-daemon', type: 'infra' },
+    { pattern: 'ingress-nginx', type: 'infra' },
+    { pattern: 'nginx-ingress', type: 'infra' },
+    { pattern: 'metrics-server', type: 'infra' },
+    { pattern: '\\bcalico\\b', type: 'infra' },
+    { pattern: '\\bcilium\\b', type: 'infra' },
+    { pattern: 'kube-proxy', type: 'infra' },
+    { pattern: 'local-path-provisioner', type: 'infra' },
+    { pattern: '\\btraefik\\b', type: 'infra' },
+];
+export function expandHome(p) {
+    const home = process.env.HOME ?? os.homedir();
+    if (p === '~')
+        return home;
+    if (p.startsWith('~/'))
+        return home + p.slice(1);
+    return p;
+}
+/**
+ * Load user classification rules. Missing or malformed file is not an
+ * error — the built-in table alone still works — so this always resolves
+ * to a (possibly empty) rule list. Entries without a string pattern/type
+ * are skipped.
+ */
+export function loadUserRules(file = DEFAULT_USER_RULES_FILE) {
+    let text;
+    try {
+        text = readFileSync(expandHome(file), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    try {
+        const doc = parseYaml(text);
+        if (!doc || !Array.isArray(doc.rules))
+            return [];
+        const rules = [];
+        for (const entry of doc.rules) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            const { pattern, type } = entry;
+            if (typeof pattern !== 'string' || typeof type !== 'string')
+                continue;
+            try {
+                new RegExp(pattern); // validate — a broken regex skips this entry only
+            }
+            catch {
+                continue;
+            }
+            rules.push({ pattern, type });
+        }
+        return rules;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Candidate signal strings for a workload: image basenames (tag stripped)
+ * and full images, chart-ish label values, and every label as `key=value`.
+ */
+function signalsOf(input) {
+    const signals = [];
+    for (const image of input.images) {
+        const basename = image.split('/').pop() ?? image;
+        signals.push(basename.replace(/:[^:]*$/, ''), basename, image);
+    }
+    for (const [key, value] of Object.entries(input.labels)) {
+        signals.push(value, `${key}=${value}`);
+    }
+    if (input.name)
+        signals.push(input.name);
+    return signals;
+}
+/** Classify one signal set against an ordered rule list; first match wins. */
+export function classifySignals(input, rules) {
+    const compiled = rules.map(r => ({ re: new RegExp(r.pattern, 'i'), type: r.type }));
+    for (const signal of signalsOf(input)) {
+        for (const { re, type } of compiled) {
+            if (re.test(signal))
+                return type;
+        }
+    }
+    return 'unknown';
+}
+/**
+ * Classify a scanned workload. Loads built-in rules, then overlays the user
+ * rules file (user rules win ties — they are consulted first).
+ */
+export function classifyWorkload(workload, opts = {}) {
+    const userRules = opts.extraRules ?? loadUserRules(opts.userRulesFile);
+    return classifySignals(workload, [...userRules, ...builtinRules]);
+}
+/** True for the middleware types worth surfacing as instances (not infra, not unknown). */
+export function isMiddlewareType(type) {
+    return type !== 'unknown' && type !== 'infra';
+}

package/lib/doctrine.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Single source for the environment tool's wording: the tool description,
+ * the one-line methodology section, and the full help text. Following the
+ * progressive-disclosure doctrine, only the one-liner lives in the system
+ * prompt; the model pulls HELP_TEXT on demand via action=help.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+export declare const HELP_POINTER = "Call environment action=help for full usage.";
+export declare const TOOL_DESCRIPTION: string;
+/** The one-line system-prompt section (registered through ops-prompts). */
+export declare const STATIC_PROMPT: string;
+export declare const HELP_TEXT = "# environment \u2014 environment inventory\n\nThe inventory maps every k8s cluster registered in ops-access: workloads,\nservices, middleware instances (classified by image/chart/label), and\nbest-effort relation edges (who connects to whom). It is regenerated by\ndeterministic scans \u2014 no LLM guessing \u2014 and persisted at\n~/.dsh-ops/environment.yaml with a per-cluster scannedAt timestamp.\n\n## Actions\n\n- overview \u2014 all clusters, compact: middleware counts by type, unknown\n  workload count, stale flag, scan time. Start here before any\n  environment-related investigation.\n- show \u2014 one cluster, full detail. Requires the cluster parameter (a\n  cluster name from overview / list_access). Returns middleware instances\n  (type/namespace/workload/service entries), the unknown bucket\n  (unrecognized workloads, still listed), and relation edges. Optional\n  filters narrow the lists: namespace (exact match) and name (substring,\n  case-insensitive; ANDed together). When filtering, edges are kept only\n  when their workload endpoint survives \u2014 for fronts edges (Service \u2192\n  workload) that endpoint is the \"to\" side.\n- refresh \u2014 re-scan every registered k8s cluster now. A cluster that is\n  unreachable keeps its previous section, marked stale. Read-only: the\n  scan resolves the ro credential tier only.\n- help \u2014 this text.\n\n## Freshness\n\nSections older than the TTL (default 1h) are re-scanned automatically on\nthe next overview/show call \u2014 you never trigger scans explicitly except\nwhen you know the environment just changed (then call refresh).\n\n## Reading edges\n\n- uses-middleware  app \u2192 middleware instance (targetType is the middleware type)\n- uses-service     app \u2192 Service (an address seen in env/ConfigMap values)\n- fronts           Service \u2192 workload it selects\n- references-secret  app \u2192 Secret, reference NAME only \u2014 values are never read\n\n## Unknown bucket\n\nWorkloads the classification table cannot identify are listed under\nunknown with name and image \u2014 they are not errors. Site-specific\ncomponents can be taught via ~/.dsh-ops/environment-rules.yaml.\n\n## Monitoring corroboration\n\nWhen a cluster has a discoverable Prometheus service (monitoring\nnamespace, port 9090), entries carry monitoring: { up, down } counts\nscraped from /api/v1/targets over a short-lived kubectl port-forward.\nA down count means Prometheus sees the instance failing \u2014 investigate\nthose first. Clusters without Prometheus simply have no monitoring data.\n\n## Anomalies\n\nEach cluster section carries rule-detected anomalies (generic k8s\nsemantics only, zero LLM):\n\n- cross-namespace-ref (info) \u2014 a workload references a Service in a\n  DIFFERENT namespace. Often legitimate for shared infrastructure, but a\n  prime suspect when an environment behaves like another one (e.g. a\n  test environment pointing at another namespace's database).\n- service-no-backend (warning) \u2014 a Service has a pod selector but its\n  Endpoints have zero ready addresses: nothing answers on it.\n\noverview lists all anomalies in one section; show annotates the involved\nentries in place with [!].";

package/lib/doctrine.js

@@ -0,0 +1,84 @@
+/**
+ * Single source for the environment tool's wording: the tool description,
+ * the one-line methodology section, and the full help text. Following the
+ * progressive-disclosure doctrine, only the one-liner lives in the system
+ * prompt; the model pulls HELP_TEXT on demand via action=help.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+export const HELP_POINTER = 'Call environment action=help for full usage.';
+export const TOOL_DESCRIPTION = 'Read the environment inventory: which middleware runs on which registered k8s cluster, and best-effort relation edges between apps and middleware. ' +
+    'Actions: overview (all clusters, compact), show (one cluster, details + edges; narrow with the optional namespace and name filters instead of paging a large output), refresh (re-scan now), help (full usage). ' +
+    'Data comes from ~/.dsh-ops/environment.yaml, refreshed automatically when older than its TTL — reads are cheap, prefer overview over blind kubectl exploration.';
+/** The one-line system-prompt section (registered through ops-prompts). */
+export const STATIC_PROMPT = [
+    '## environment — 环境清单',
+    `排查环境问题前先 \`environment\` action=overview 看环境全貌（集群/中间件/关联边），不要从零 kubectl 摸索。${HELP_POINTER}`,
+].join('\n');
+export const HELP_TEXT = `# environment — environment inventory
+
+The inventory maps every k8s cluster registered in ops-access: workloads,
+services, middleware instances (classified by image/chart/label), and
+best-effort relation edges (who connects to whom). It is regenerated by
+deterministic scans — no LLM guessing — and persisted at
+~/.dsh-ops/environment.yaml with a per-cluster scannedAt timestamp.
+
+## Actions
+
+- overview — all clusters, compact: middleware counts by type, unknown
+  workload count, stale flag, scan time. Start here before any
+  environment-related investigation.
+- show — one cluster, full detail. Requires the cluster parameter (a
+  cluster name from overview / list_access). Returns middleware instances
+  (type/namespace/workload/service entries), the unknown bucket
+  (unrecognized workloads, still listed), and relation edges. Optional
+  filters narrow the lists: namespace (exact match) and name (substring,
+  case-insensitive; ANDed together). When filtering, edges are kept only
+  when their workload endpoint survives — for fronts edges (Service →
+  workload) that endpoint is the "to" side.
+- refresh — re-scan every registered k8s cluster now. A cluster that is
+  unreachable keeps its previous section, marked stale. Read-only: the
+  scan resolves the ro credential tier only.
+- help — this text.
+
+## Freshness
+
+Sections older than the TTL (default 1h) are re-scanned automatically on
+the next overview/show call — you never trigger scans explicitly except
+when you know the environment just changed (then call refresh).
+
+## Reading edges
+
+- uses-middleware  app → middleware instance (targetType is the middleware type)
+- uses-service     app → Service (an address seen in env/ConfigMap values)
+- fronts           Service → workload it selects
+- references-secret  app → Secret, reference NAME only — values are never read
+
+## Unknown bucket
+
+Workloads the classification table cannot identify are listed under
+unknown with name and image — they are not errors. Site-specific
+components can be taught via ~/.dsh-ops/environment-rules.yaml.
+
+## Monitoring corroboration
+
+When a cluster has a discoverable Prometheus service (monitoring
+namespace, port 9090), entries carry monitoring: { up, down } counts
+scraped from /api/v1/targets over a short-lived kubectl port-forward.
+A down count means Prometheus sees the instance failing — investigate
+those first. Clusters without Prometheus simply have no monitoring data.
+
+## Anomalies
+
+Each cluster section carries rule-detected anomalies (generic k8s
+semantics only, zero LLM):
+
+- cross-namespace-ref (info) — a workload references a Service in a
+  DIFFERENT namespace. Often legitimate for shared infrastructure, but a
+  prime suspect when an environment behaves like another one (e.g. a
+  test environment pointing at another namespace's database).
+- service-no-backend (warning) — a Service has a pod selector but its
+  Endpoints have zero ready addresses: nothing answers on it.
+
+overview lists all anomalies in one section; show annotates the involved
+entries in place with [!].`;

package/lib/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Environment inventory tool plugin (preset plane).
+ *
+ * Registers the model-facing `environment` tool (overview / show / refresh /
+ * help) on top of the ticket-01 scanner core. The tool resolves the
+ * ops-access seam per call via ctx.get — never a static inject, never
+ * cached — so it must be mounted in the same isolate realm as opsAccess
+ * (the `ops-access-registry` group in ops-preset.yml). The one-line
+ * methodology section lives in the `./prompt` subpath plugin, mounted with
+ * the prompt-channel consumers.
+ *
+ * apply() only registers the tool: nothing scans at session start. Scans
+ * happen on explicit refresh, or on a read whose oldest section is past
+ * the TTL.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { EnvironmentToolConfig } from './tool.js';
+export declare const name = "ops-tool-environment";
+export declare const inject: string[];
+export declare const Config: z<EnvironmentToolConfig>;
+export declare function apply(ctx: Context, config: EnvironmentToolConfig): void;
+export type { Anomaly, ClassifiedWorkload, ClusterInventory, ClusterScan, MiddlewareInstance, MonitoringStatus, PromTarget, RelationEdge, ResourceRef, ScannedConfigMap, ScannedEndpoints, ScannedIngress, ScannedSecret, ScannedService, ScannedWorkload, } from './types.js';
+export { builtinRules, classifySignals, classifyWorkload, DEFAULT_USER_RULES_FILE, expandHome, isMiddlewareType, loadUserRules, } from './classify.js';
+export type { ClassificationRule, ClassifyInput } from './classify.js';
+export { defaultExec, ScanError, SCAN_TIMEOUT_MS, scanCluster, scrubKubeconfigPath, } from './scanner.js';
+export type { ExecFn, ScanClusterInput } from './scanner.js';
+export { buildRelations, findServiceAddresses } from './relations.js';
+export type { BuildRelationsInput } from './relations.js';
+export { detectAnomalies } from './anomalies.js';
+export type { DetectAnomaliesInput } from './anomalies.js';
+export { findPrometheusService, matchTargetsToWorkloads, parseActiveTargets, scrapePrometheusTargets, } from './prometheus.js';
+export type { PortForwardProcess, ScrapeOptions, SpawnFn } from './prometheus.js';
+export { buildClusterInventory, DEFAULT_INVENTORY_FILE, readInventory, refreshInventory, } from './inventory.js';
+export type { EnvironmentInventory, InventorySection, RefreshOptions, RefreshTarget, } from './inventory.js';
+export { createEnvironmentTool, filterDetail } from './tool.js';
+export type { ClusterDetail, ClusterSummary, DisplayAnomaly, DisplayEdge, EnvironmentToolConfig, EnvironmentToolDeps, EnvironmentToolResult, OverviewAnomaly, RefreshResultEntry, ShowFilter, UnknownWorkload, } from './tool.js';
+export { HELP_POINTER, HELP_TEXT, STATIC_PROMPT, TOOL_DESCRIPTION } from './doctrine.js';