@morlay/dsh-context-assembler 0.0.1-alpha.2

package/src/agent-instructions/files.ts

@@ -0,0 +1,117 @@
+import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+/** 一条要注入的指令文件：`display` 进 id 与正文，`path` 用来读，`root` 区分同名文件。 */
+export interface InstructionFile {
+  /** 该文件所属的根（项目根或 `$DSH_HOME`）：规则块 id 靠它区分不同根下的同名文件。 */
+  readonly root: string;
+  readonly display: string;
+  readonly path: string;
+}
+
+export interface WorkspaceOptions {
+  readonly instructionFileCandidates: readonly string[];
+  readonly localInstructionFileCandidates: readonly string[];
+  readonly dshHome: string;
+}
+
+/** 从 cwd 逐级向上找项目根（含标记目录的那一级）。 */
+async function projectRoot(cwd: string, marker = ".git"): Promise<string | undefined> {
+  let current = resolve(cwd);
+  for (;;) {
+    const found = await stat(join(current, marker)).then(
+      () => true,
+      () => false,
+    );
+    if (found) return current;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+function abbreviateHome(path: string): string {
+  const home = homedir();
+  return path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+
+/**
+ * 工作区指令链：用户全局 `$DSH_HOME/AGENTS.md`，再从项目根到 cwd 的每一级目录取
+ * 基础文件与本地 overlay。顺序由宽泛到具体——具体的在后面，与"更具体的优先"一致。
+ */
+export async function instructionChain(
+  cwd: string,
+  options: WorkspaceOptions,
+): Promise<InstructionFile[]> {
+  const files: InstructionFile[] = [];
+  const global = join(options.dshHome, "AGENTS.md");
+  if (await isFile(global))
+    files.push({ root: options.dshHome, display: abbreviateHome(global), path: global });
+
+  const root = (await projectRoot(cwd)) ?? resolve(cwd);
+  const levels: string[] = [];
+  let current = resolve(cwd);
+  for (;;) {
+    levels.unshift(current);
+    if (current === root) break;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  for (const level of levels) {
+    for (const name of [
+      ...options.instructionFileCandidates,
+      ...options.localInstructionFileCandidates,
+    ]) {
+      const path = join(level, name);
+      if (await isFile(path)) files.push({ root, display: relativeDisplay(root, path), path });
+    }
+  }
+  return files;
+}
+
+function relativeDisplay(root: string, path: string): string {
+  const rel = path.slice(root.length + 1);
+  return rel.length === 0 ? path : rel;
+}
+
+async function isFile(path: string): Promise<boolean> {
+  const info = await stat(path).then(
+    (value) => value,
+    () => undefined,
+  );
+  return info?.isFile() === true;
+}
+
+/** 读一个指令文件；按 `mtimeMs:size` 缓存，未变就不重读。 */
+export async function readInstruction(
+  file: InstructionFile,
+  cache: Map<string, { stamp: string; text: string }>,
+  maxBytes: number,
+): Promise<string> {
+  const info = await stat(file.path).then(
+    (value) => value,
+    () => undefined,
+  );
+  if (info?.isFile() !== true) {
+    cache.delete(file.path);
+    return "";
+  }
+  const stamp = `${String(info.mtimeMs)}:${String(info.size)}`;
+  const cached = cache.get(file.path);
+  if (cached?.stamp === stamp) return cached.text;
+  const raw = await readFile(file.path, "utf8").catch(() => "");
+  const text = budget(raw, file.display, maxBytes);
+  cache.set(file.path, { stamp, text });
+  return text;
+}
+
+/** 单文件超出预算时截断并留一行可见提示（不静默丢内容）。 */
+function budget(text: string, display: string, maxBytes: number): string {
+  if (Buffer.byteLength(text, "utf8") <= maxBytes) return text.trimEnd();
+  const kept = Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8");
+  const lastBreak = kept.lastIndexOf("\n");
+  const body = (lastBreak > 0 ? kept.slice(0, lastBreak) : kept).trimEnd();
+  return `${body}\n\n(Workspace instruction budget ${String(maxBytes)} bytes: ${display} is truncated.)`;
+}

package/src/agent-instructions/index.ts

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type {} from "@deepseek-ai/dsh-agent-instructions";
+import z from "@deepseek-ai/schemastery";
+import type {} from "../assembler/index.ts";
+import { instructionChain, readInstruction, type InstructionFile } from "./files.ts";
+import { baselineIdentity } from "./baseline.ts";
+
+export const name = "context-agent-instructions";
+
+export const inject = ["agents", "contextAssembler"];
+
+export interface Config {
+  /** 每级目录的基础指令文件名。 */
+  instructionFileCandidates?: string[];
+  /** 基础文件之后加载的本地 overlay 名。 */
+  localInstructionFileCandidates?: string[];
+  /** 单个指令文件的渲染上限（字节）。 */
+  maxBytes?: number;
+  /** 用户全局指令所在目录（默认 `$DSH_HOME` 或 `~/.dsh`）。 */
+  dshHome?: string;
+}
+
+export const Config: z<Config> = z.object({
+  instructionFileCandidates: z.array(z.string()).default(["AGENTS.md"]),
+  localInstructionFileCandidates: z.array(z.string()).default(["AGENTS.local.md"]),
+  maxBytes: z.number().default(65536),
+  dshHome: z.string().default(process.env["DSH_HOME"] ?? ""),
+});
+
+/** 一个会话的指令链：路径集合与它所属的 cwd。 */
+const chains = new WeakMap<Agent, { cwd: string; files: InstructionFile[] }>();
+
+/**
+ * 工作区指令：一条文件一个规则块（id 为 `agent-instructions:<根标识>:<文件>`），文件变化时正文变、按 id 覆盖。
+ *
+ * 与上游 `agent-instructions` 的差别：不做 read/write/edit 的 touch 跟踪（本部署的 `AGENTS.md`
+ * 几乎不变），只在每步按 `mtime:size` 对账；一份文件一条 id，于是变化只重发变了的那一份。
+ */
+export function apply(ctx: Context, config: Config): void {
+  const options = {
+    instructionFileCandidates: config.instructionFileCandidates ?? ["AGENTS.md"],
+    localInstructionFileCandidates: config.localInstructionFileCandidates ?? ["AGENTS.local.md"],
+    dshHome:
+      config.dshHome === undefined || config.dshHome === "" ? defaultDshHome() : config.dshHome,
+  };
+  const maxBytes = config.maxBytes ?? 65536;
+  const cache = new Map<string, { stamp: string; text: string }>();
+
+  const install = async (agent: Agent): Promise<void> => {
+    if (chains.has(agent)) return;
+    const cwd = agent.session.header.cwd === undefined ? process.cwd() : agent.session.header.cwd;
+    const chain = { cwd, files: await instructionChain(cwd, options) };
+    chains.set(agent, chain);
+    // 上游认领判据要的身份：缺它，上游（官方 preset 自己装的那行）会以为基线不存在，再注入一条自己的模板。
+    const identity = await baselineIdentity(cwd);
+    for (const file of chain.files) {
+      ctx.contextAssembler.registerRule({
+        id: `agent-instructions:${rootTag(file.root)}:${file.display}`,
+        // 对外身份沿用上游那两样：kind 让客户端标签与按 kind 认领的消费方（上游的实验性约束收集）认得这是
+        // 工作区指令；`baseline` 与 `baselineIdentity` 让上游的认领判据（kind + baseline===true + 身份相等）
+        // 认这份条目就是基线，于是它不再注入自己那条模板。`changes` 留空——上游那套按文件做 reconciliation
+        // 的记录我们不做（一条文件一条 id）。
+        source: () => ({
+          kind: "agent-instructions",
+          form: "instructions",
+          baseline: true,
+          baselineIdentity: identity,
+          changes: [],
+        }),
+        text: (target) => {
+          const current = chains.get(target);
+          if (current === undefined || !current.files.some((entry) => entry.path === file.path))
+            return "";
+          return readInstruction(file, cache, maxBytes);
+        },
+      });
+    }
+  };
+
+  ctx.on("agent/created", ({ agent }) => {
+    void install(agent).catch((error: unknown) => {
+      ctx.logger.warn(`context-agent-instructions: ${String(error)}`);
+    });
+  });
+  for (const agent of ctx.agents.list()) {
+    void install(agent).catch((error: unknown) => {
+      ctx.logger.warn(`context-agent-instructions: ${String(error)}`);
+    });
+  }
+}
+
+function defaultDshHome(): string {
+  const home = process.env["HOME"] ?? "~";
+  return resolve(process.env["DSH_HOME"] ?? `${home}/.dsh`);
+}
+
+/**
+ * 规则块 id 里的根标识：规则声明是**全局按 id 覆盖**的，而 `display` 只是根内相对路径——
+ * 同进程里两个项目根都有 `AGENTS.md` 时，不带根标识的 id 会互相顶掉（后注册者覆盖前者，
+ * 前者此后读到空正文）。8 位摘要够唯一，又不把绝对路径塞进提示词 id。
+ */
+function rootTag(root: string): string {
+  return createHash("sha256").update(root).digest("hex").slice(0, 8);
+}

package/src/assembler/channel.ts

@@ -0,0 +1,285 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import { Service, type Context } from "@deepseek-ai/cordis";
+import type { MessageSource } from "@deepseek-ai/dsh-llm";
+import { renderReminder, renderVirtualSkill } from "./reminder.ts";
+
+/** 正文到达模型的方式：自动注入，或等模型按需加载。 */
+export type InjectionMode = "auto" | "on-demand";
+
+/**
+ * 一条按 skill 形态声明的注入：正文是本仓库维护的文案。
+ *
+ * 正文与 agent 无关（工具集在装配期就定了），所以 skill 在装配期注册一次、全局可见。
+ */
+export interface PromptSkillDeclaration {
+  /** kebab-case：skill 名，也是注入条目的 id。 */
+  readonly name: string;
+  readonly title: string;
+  /** 目录行摘要：讲清什么时候该加载它。 */
+  readonly description: string;
+  /**
+   * 正文按**会话**生成：模式可能只给一部分工具，正文要跟着修剪（不该讲用不到的工具）。
+   * 不传 agent（装配期注册 skill 时）返回不过滤的完整版。
+   */
+  readonly content: (agent?: Agent) => string;
+  /**
+   * 这个 skill 赖以成立的**入口工具**（任一存在即可，不是全部）。都不可见时它不该出现在该会话的技能
+   * 目录里——"不能用 skill 工具就没有技能目录"是同一个道理：技能也跟着工具走。
+   *
+   * 缺省语义就是"一个都不在就藏起来"；声明方要自己挑入口，别把组内所有可能的工具都倒进来
+   * （子代理控制行与团队插件会提供同名工具，全集当判据会把不该出现的 skill 留下）。
+   */
+  readonly requires?: readonly string[];
+  /** 缺省 `on-demand`：只有正文确有必要常驻时才写 `auto`。 */
+  readonly injection?: InjectionMode;
+}
+
+interface RegisteredSkill {
+  readonly digest: string;
+  readonly dispose: () => void;
+}
+
+interface AgentState {
+  /** 本步装配降级出来的 section 条目：id → 正文（未渲染信封）。 */
+  sections: ReadonlyMap<string, string>;
+}
+
+/**
+ * 一条规则块声明：系统级信息（工作区指令、skill 目录），文本按 id 幂等注入、同 id 覆盖。
+ * 文本可以是异步的（skill 目录要读 skill 注册表）。
+ */
+export interface PromptRuleDeclaration {
+  readonly id: string;
+  readonly text: (agent: Agent) => string | Promise<string>;
+  /**
+   * 这条规则的对外身份。接管上游那两面（工作区指令 / skill 目录）按上游 kind 发消息，好让按 kind 认领的
+   * 消费方（客户端标签、上游的实验性约束收集）认得出来；不声明就是通道自己的 `context-assembler`。
+   * 幂等键仍是 `id`（`reminderMessage` 会把它塞进 source）。
+   */
+  readonly source?: (agent: Agent) => MessageSource;
+}
+
+/** 一条待注入的条目：正文已渲染好，`source` 是它声明给外部的身份。 */
+export interface PromptEntry {
+  readonly text: string;
+  readonly source?: MessageSource;
+}
+
+/**
+ * 注入通道：调用方声明「什么内容、怎么到达模型」，这里负责到达方式。
+ *
+ * - `on-demand`：注册成模型可用 skill（进 skill 目录，正文按需加载）；
+ * - `auto`：正文自动注入 reminder（注册成 skill 但标 `modelInvocable: false`，因为已经常驻）；
+ * - `replaceSection` / `suppressSection`：装配结果上的文本改写与丢弃。
+ *
+ * 覆盖语义（同 id 最新取代更早）由系统提示词里的声明说明一次，见 [`rules.ts`](./rules.ts)。
+ */
+export class ContextAssembler extends Service {
+  private readonly declarations = new Map<string, PromptSkillDeclaration>();
+  private readonly rules = new Map<string, PromptRuleDeclaration>();
+  private readonly overrides = new Map<string, (agent: Agent) => string | undefined>();
+  private readonly suppressed = new Set<string>();
+  private readonly skills = new Map<string, RegisteredSkill>();
+  private readonly states = new WeakMap<Agent, AgentState>();
+  /** 不要 instruction 类注入（规则块）的会话；内容块（技能正文、引用材料）不受它管。 */
+  private readonly withoutInstructions = new WeakSet<Agent>();
+
+  /** 本会话的模式收窄（白名单）：投影层的过滤不碰注册表，注册表上看不出"谁能用"。 */
+  private readonly toolScopes = new WeakMap<Agent, (tool: string) => boolean>();
+
+  /** `host` 是构造期那个根 ctx：`skills` 的访问权限挂在插件的 inject 声明上，不能依赖访问者 ctx。 */
+  constructor(private readonly host: Context) {
+    super(host, "contextAssembler");
+  }
+
+  registerSkill(declaration: PromptSkillDeclaration): () => void {
+    this.declarations.set(declaration.name, declaration);
+    this.refreshSkills();
+    return () => {
+      if (this.declarations.get(declaration.name) !== declaration) return;
+      this.declarations.delete(declaration.name);
+      this.refreshSkills();
+    };
+  }
+
+  registerRule(declaration: PromptRuleDeclaration): () => void {
+    this.rules.set(declaration.id, declaration);
+    return () => {
+      if (this.rules.get(declaration.id) === declaration) this.rules.delete(declaration.id);
+    };
+  }
+
+  replaceSection(name: string, text: (agent: Agent) => string | undefined): () => void {
+    this.overrides.set(name, text);
+    return () => {
+      if (this.overrides.get(name) === text) this.overrides.delete(name);
+    };
+  }
+
+  suppressSection(name: string): () => void {
+    this.suppressed.add(name);
+    return () => {
+      this.suppressed.delete(name);
+    };
+  }
+
+  isSuppressed(name: string): boolean {
+    return this.suppressed.has(name);
+  }
+
+  /** 装配结果上该 section 要换成的文本；undefined 表示原样保留。 */
+  replacement(name: string, agent: Agent | undefined): string | undefined {
+    const override = this.overrides.get(name);
+    return override === undefined || agent === undefined ? undefined : override(agent);
+  }
+
+  /**
+   * 本步要注入的条目：键 → 已渲染好的正文（规则块或内容块）。
+   * `sections` 来自本步装配，`rules` 与 `auto` skill 正文在这里现算。
+   */
+  /** 这个会话不要 instruction 类的规则块（模式说了 `instructions: false`）。 */
+  setInstructions(agent: Agent, on: boolean): void {
+    if (on) this.withoutInstructions.delete(agent);
+    else this.withoutInstructions.add(agent);
+  }
+
+  /**
+   * 本会话的**工具收窄**（模式白名单）：投影层只过滤装配结果、不碰工具注册表，所以"谁能用"这件事
+   * 必须在通道上登记，技能目录与组正文才收得住。与 {@link setInstructions} 同形——谓词由模式那一行给
+   * （`context-scope`），通道自己不碰 `tools` 服务。
+   */
+  restrictTools(agent: Agent, allowed: (tool: string) => boolean): void {
+    this.toolScopes.set(agent, allowed);
+  }
+
+  /**
+   * 本会话的工具可见性：调用方给出的注册表可见性 × 已登记的模式收窄。技能目录与组正文共用它，
+   * 免得同一套判据在几处各写一遍。
+   */
+  visibleTools(agent: Agent, registered: (tool: string) => boolean): (tool: string) => boolean {
+    const allowed = this.toolScopes.get(agent);
+    return allowed === undefined ? registered : (tool) => registered(tool) && allowed(tool);
+  }
+
+  /**
+   * 该会话看不到的 skill 名：声明了 `requires` 而依赖的工具一个都不可见。
+   *
+   * 目录由 `context-skill-catalog` 渲染，它把工具可见性作为谓词传进来（通道不碰 tools 服务）。
+   */
+  hiddenSkills(visible: (tool: string) => boolean): ReadonlySet<string> {
+    const hidden = new Set<string>();
+    for (const [name, declaration] of this.declarations) {
+      const requires = declaration.requires;
+      if (requires === undefined || requires.length === 0) continue;
+      if (!requires.some(visible)) hidden.add(name);
+    }
+    return hidden;
+  }
+
+  /**
+   * 该 skill 按会话修剪后的正文：注册表只能存一份（技能注册是装配期一次、全局可见），所以按需加载
+   * 路径（接管的 `skill` 工具）要用这里重新算一次，才和 `auto` 正文一样跟着工具走。
+   */
+  contentFor(name: string, agent: Agent | undefined): string | undefined {
+    return this.declarations.get(name)?.content(agent);
+  }
+
+  async collect(agent: Agent): Promise<Map<string, PromptEntry>> {
+    const entries = new Map<string, PromptEntry>();
+    for (const declaration of this.declarations.values()) {
+      if ((declaration.injection ?? "on-demand") !== "auto") continue;
+      const body = declaration.content(agent);
+      // 常驻送达的 skill 正文与按需加载同一形态：内容块，不是规则块。
+      if (body.length > 0)
+        entries.set(declaration.name, { text: renderVirtualSkill(declaration.name, body) });
+    }
+    const instructionsOff = this.withoutInstructions.has(agent);
+    for (const declaration of this.rules.values()) {
+      if (instructionsOff) break;
+      // 注入路径不能被任何一个内容提供者拖死：文本是异步算的（技能目录要读注册表、工作区指令要读文件），
+      // 谁卡住都不该让人等在这里——超时或抛错都按"这条没有内容"处理。
+      const text = await withTimeout(declaration.text(agent), CONTENT_TIMEOUT_MS);
+      if (text.length > 0) {
+        entries.set(declaration.id, {
+          text: renderReminder(declaration.id, text),
+          ...(declaration.source === undefined ? {} : { source: declaration.source(agent) }),
+        });
+      }
+    }
+    if (!instructionsOff) {
+      for (const [id, text] of this.sectionsOf(agent)) {
+        entries.set(id, { text: renderReminder(id, text) });
+      }
+    }
+    return entries;
+  }
+
+  private sectionsOf(agent: Agent): ReadonlyMap<string, string> {
+    return this.states.get(agent)?.sections ?? new Map();
+  }
+
+  /**
+   * 每步装配调一次：记下本步降级出来的 section 文本，供下一步注入。
+   */
+  sync(agent: Agent, input: { readonly sections: ReadonlyMap<string, string> }): void {
+    this.stateOf(agent).sections = input.sections;
+  }
+
+  /** skill 注册（装配期一次，全局可见）：正文没变的不重注册。 */
+  private refreshSkills(agent?: Agent): void {
+    for (const [name, declaration] of this.declarations) {
+      const content = declaration.content(agent);
+      const modelInvocable = (declaration.injection ?? "on-demand") === "on-demand";
+      const digest = `${modelInvocable ? "model" : "auto"}\u0000${declaration.description}\u0000${content}`;
+      const current = this.skills.get(name);
+      if (current?.digest === digest) continue;
+      current?.dispose();
+      const dispose = this.host.skills.register({
+        name,
+        description: declaration.description,
+        content,
+        source: "runtime",
+        invocation: { modelInvocable, userInvocable: true },
+      });
+      this.skills.set(name, { digest, dispose });
+    }
+    for (const [name, registered] of this.skills) {
+      if (this.declarations.has(name)) continue;
+      registered.dispose();
+      this.skills.delete(name);
+    }
+  }
+
+  private stateOf(agent: Agent): AgentState {
+    const existing = this.states.get(agent);
+    if (existing !== undefined) return existing;
+    const state: AgentState = { sections: new Map() };
+    this.states.set(agent, state);
+    return state;
+  }
+}
+
+declare module "@deepseek-ai/cordis" {
+  interface Context {
+    contextAssembler: ContextAssembler;
+  }
+}
+
+/** 一条注入内容的取用上限：超过就按"没有内容"处理，不阻塞这一轮请求。 */
+const CONTENT_TIMEOUT_MS = 2000;
+
+async function withTimeout(work: string | Promise<string>, ms: number): Promise<string> {
+  if (typeof work === "string") return work;
+  const settled = Promise.resolve(work).catch(() => "");
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expiry = new Promise<string>((resolve) => {
+    timer = setTimeout(() => {
+      resolve("");
+    }, ms);
+  });
+  try {
+    return await Promise.race([settled, expiry]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}

package/src/assembler/defaults.ts

@@ -0,0 +1,53 @@
+import { PERSONA_PREFIX_SECTION, PERSONA_SUFFIX_SECTION } from "@deepseek-ai/dsh-system-prompt";
+import { RULES_SECTION } from "./reminder.ts";
+
+/**
+ * 留在系统提示词里的 section：部署级 persona（子 agent 在 agent 作用域注册的同名 persona 也命中）
+ * 与覆盖规则声明（[`rules.ts`](./rules.ts)）。
+ */
+export const DEFAULT_KEEP: readonly string[] = [
+  PERSONA_PREFIX_SECTION,
+  PERSONA_SUFFIX_SECTION,
+  RULES_SECTION,
+];
+
+/**
+ * 不进提示词的 section。三类：
+ *
+ * 1. **harness 自带的开场白与平台运维说明**：`harness:identity`（"You are an AI agent powered by
+ *    DeepSeek Harness."——身份由各模式的 persona 给，这句话在本部署里是噪音，且是英文）、
+ *    `harness:source`（讲 dev server / HMR / 本地 checkout 位置）；
+ * 2. 本部署不装配的工具的用法说明：`tool:lsp` / `tool:pty` / `tool:session-query` / `tool:cordis` /
+ *    `tool:ralph`；
+ * 3. `app:web-surface`（平台外壳说明）。
+ *
+ * 其余工具说明由各组的 `drops` 摘掉、要点由 toolkit 的 `guidance` 出口写进组正文，不在这一份里。
+ */
+export const DEFAULT_SUPPRESS: readonly string[] = [
+  "harness:identity",
+  "harness:source",
+  "app:web-surface",
+  "tool:lsp",
+  "tool:pty",
+  "tool:session-query",
+  "tool:cordis",
+  "tool:ralph",
+];
+
+/**
+ * 改写成中文的两段上游说明（内容忠实原意）：`@` 引用路径的语义、输出里的文件链接规范。
+ *
+ * 这两段注册在 agent 层（`context:file-reference`）与 host 层（`ui:deliverable-file-references`），
+ * 注册层不归我们——所以在装配结果上换文本（不移除：内容要保留）。
+ */
+export const DEFAULT_REPLACE: Readonly<Record<string, string>> = {
+  "context:file-reference":
+    "以 @ 开头的词是用户显式引用的工作区路径，相对于工作区根。结尾带斜杠表示目录：需要时列目录内容。" +
+    "其余是文件：需要内容时用 read 工具读取，不要在读取前声称自己已经看过。" +
+    '用 @"..." 括住含空格的路径。',
+  "ui:deliverable-file-references":
+    "成功创建或修改文件后，在最终回复里点明主要产物。除命令、配置表达式与代码块之外，" +
+    "每处提到已存在的文件都要链到它的完整路径（相对工作目录或绝对路径）；已知行号时在目标后加 " +
+    "`#L24` 或 `#L24-L30`。链接文本用文件名或清晰别名，只加够区分的父目录，不要把完整路径放进标签；" +
+    "默认只用文件名，需要精确位置时在标签后接 `:24` 或 `:24–30`（不带 `#` 或 `L`）。",
+};