dsh-switchman 1.3.0

package/skills/db-query/scripts/mysql-query.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * MySQL 只读查询入口
+ * 编排流程：CLI 解析 → SQL 只读校验 → 建连（只读事务+超时）→ 查询 → 输出 → 回滚关闭
+ * 安全要点：客户端 timer + 服务端 MAX_EXECUTION_TIME 双保险；永远 ROLLBACK
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── 内部模块 ──
+const { parseCli, CliError } = require('./lib/cli');
+const { loadEnvFile, resolveEnv, resolveEnvNumber, ConfigError, sanitizeTarget, safeMessage, buildTlsOptions } = require('./lib/config');
+const { validateMysqlSql, ReadonlyError } = require('./lib/mysql-readonly');
+const { formatMysqlTable, formatJson } = require('./lib/output');
+
+// ── CLI 参数规格 ──
+const MYSQL_SPEC = {
+  host:              { type: 'string', default: '127.0.0.1' },
+  port:              { type: 'integer', default: 3306, min: 1, max: 65535 },
+  user:              { type: 'string', default: undefined },
+  password:          { type: 'string', default: undefined },
+  database:          { type: 'string', default: undefined },
+  tls:               { type: 'boolean', default: false },
+  'ca-file':         { type: 'string', default: undefined },
+  'connect-timeout-ms': { type: 'integer', default: 5000, min: 1000, max: 30000 },
+  'timeout-ms':      { type: 'integer', default: 10000, min: 1000, max: 60000 },
+  'max-rows':        { type: 'integer', default: 200, min: 1, max: 5000 },
+  'max-value-bytes': { type: 'integer', default: 4096, min: 256, max: 1048576 },
+  format:            { type: 'string', default: 'table', choices: ['table', 'json'] },
+  'env-file':        { type: 'string', default: undefined },
+  'validate-only':   { type: 'boolean', default: false },
+  file:              { type: 'string', default: undefined },
+};
+
+const ENV_PREFIX = 'DB_QUERY_MYSQL_';
+
+/** 从文件读取 SQL（限 64KiB 普通文本） */
+function readSqlFile(filePath) {
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) throw new Error(`SQL 文件不存在: ${resolved}`);
+  const stat = fs.statSync(resolved);
+  if (stat.size > 64 * 1024) throw new Error(`SQL 文件超过 64KiB: ${resolved}`);
+  return fs.readFileSync(resolved, 'utf8');
+}
+
+/** 打印校验结果（--validate-only 模式） */
+function printValidation(checked) {
+  process.stderr.write(`✓ 校验通过: ${checked.kind}${checked.limitInjected ? ' (已注入 LIMIT 截断)' : ''}\n`);
+  process.stderr.write(`处理后的 SQL:\n${checked.sql}\n`);
+}
+
+/** 带超时的查询执行（客户端 timer + 服务端 MAX_EXECUTION_TIME 双保险） */
+function queryWithTimeout(conn, sql, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      // 客户端超时：销毁连接，避免服务端继续传输
+      conn.destroy();
+      reject(new Error(`查询超时 (${timeoutMs}ms)`));
+    }, timeoutMs);
+
+    conn.query(sql)
+      .then(result => { clearTimeout(timer); resolve(result); })
+      .catch(err => { clearTimeout(timer); reject(err); });
+  });
+}
+
+/** 安全回滚（忽略错误，确保连接一定关闭） */
+async function safeRollback(conn) {
+  try { await conn.query('ROLLBACK'); } catch (_) { /* 事务不存在等错误忽略 */ }
+}
+
+/** 安全关闭连接 */
+async function safeClose(conn) {
+  try { await conn.end(); } catch (_) { /* 连接已断开等错误忽略 */ }
+}
+
+// ── 主函数 ──
+async function main() {
+  const { options, rest } = parseCli(process.argv.slice(2), MYSQL_SPEC);
+
+  // SQL 来源校验：--file 和位置参数二选一
+  if (options.file && rest.length > 0) {
+    throw new CliError('--file 和位置参数 SQL 不能同时指定');
+  }
+  if (!options.file && rest.length === 0) {
+    throw new CliError('必须指定 SQL（位置参数或 --file）');
+  }
+
+  // 读取 SQL（在任何连接操作之前）
+  const rawSql = options.file ? readSqlFile(options.file) : rest[0];
+
+  // 只读校验（纯离线，不依赖任何连接参数）
+  const maxRows = options.maxRows;
+  const checked = validateMysqlSql(rawSql, { maxRows });
+
+  // --validate-only：纯离线校验，不解析凭据、不建连
+  if (options['validate-only']) {
+    return printValidation(checked);
+  }
+
+  // ── 以下为连库路径，需要连接参数 ──
+  // 修复：env 文件加载必须在 user/database 必填检查之前，否则 env 文件提供的凭据读不到
+  const envPairs = loadEnvFile(options['env-file']);
+
+  // 合并环境变量覆盖（统一用 resolveEnvNumber 做边界校验，防 env 文件绕过硬上限）
+  const host = resolveEnv(envPairs, ENV_PREFIX + 'HOST', options.host);
+  const port = resolveEnvNumber(envPairs, ENV_PREFIX + 'PORT', options.port, { min: 1, max: 65535 });
+  const user = resolveEnv(envPairs, ENV_PREFIX + 'USER', options.user);
+  const password = resolveEnv(envPairs, ENV_PREFIX + 'PASSWORD', options.password);
+  const database = resolveEnv(envPairs, ENV_PREFIX + 'DATABASE', options.database);
+
+  // user 必填；database 放宽为可选——排查第一步常是 SHOW DATABASES / SELECT 1 /
+  // 带库名前缀的表查询，不强制默认库；查表未指定库时 MySQL 会自报 ER_NO_DB_ERROR
+  if (!user) throw new CliError('缺少 user（用 --user、DB_QUERY_MYSQL_USER、环境变量或 env 文件提供）');
+  if (!database) {
+    process.stderr.write('（未指定 database：仅能执行无默认库的查询，如 SHOW DATABASES / SELECT 1 / 带库名前缀的表）\n');
+  }
+
+  const maxRowsResolved = resolveEnvNumber(envPairs, ENV_PREFIX + 'MAX_ROWS', options.maxRows, { min: 1, max: 5000 });
+  const maxValueBytes = resolveEnvNumber(envPairs, 'DB_QUERY_MAX_VALUE_BYTES', options['max-value-bytes'], { min: 256, max: 1048576 });
+  const timeoutMs = resolveEnvNumber(envPairs, ENV_PREFIX + 'TIMEOUT_MS', options['timeout-ms'], { min: 1000, max: 60000 });
+  const connectTimeoutMs = resolveEnvNumber(envPairs, ENV_PREFIX + 'CONNECT_TIMEOUT_MS', options['connect-timeout-ms'], { min: 1000, max: 30000 });
+
+  // 打印脱敏目标（连库前确认去向，绝不暴露密码）
+  const target = sanitizeTarget({ host, port, user, database });
+  process.stderr.write(`→ MySQL ${target}\n`);
+
+  // 动态加载 mysql2（只在需要连库时）
+  const mysql = require('mysql2/promise');
+
+  const conn = await mysql.createConnection({
+    host,
+    port,
+    user,
+    password: password || undefined,
+    database,
+    connectTimeout: connectTimeoutMs,
+    multipleStatements: false,   // 显式关闭，不依赖驱动默认值
+    supportBigNumbers: true,
+    bigNumberStrings: true,     // BIGINT/DECIMAL 保留字符串精度
+    decimalNumbers: false,
+    dateStrings: true,          // 日期保留服务端文本
+    ...(options.tls || options['ca-file']
+      ? { ssl: buildTlsOptions(options['ca-file']) || { rejectUnauthorized: true } }
+      : {}),
+  });
+
+  const startMs = Date.now();
+  try {
+    // 服务端只读事务（不支持的版本会报错，fail-closed 不静默降级）
+    await conn.query('SET SESSION TRANSACTION READ ONLY');
+    await conn.query('SET SESSION MAX_EXECUTION_TIME = ?', [timeoutMs]);
+    await conn.query('START TRANSACTION READ ONLY');
+
+    const [rows, fields] = await queryWithTimeout(conn, checked.sql, timeoutMs);
+    const elapsedMs = Date.now() - startMs;
+
+    // 判断是否有截断（LIMIT 注入了 maxRows+1 哨兵行）
+    const truncated = checked.limitInjected && rows.length > maxRowsResolved;
+    const displayRows = truncated ? rows.slice(0, maxRowsResolved) : rows;
+
+    if (options.format === 'json') {
+      // JSON 写 stdout，状态写 stderr，保证 stdout 是合法 JSON
+      process.stdout.write(JSON.stringify({
+        source: 'mysql',
+        target,
+        elapsedMs,
+        count: truncated ? maxRowsResolved : rows.length,
+        truncated,
+        result: displayRows,
+      }, null, 2) + '\n');
+    } else {
+      process.stdout.write(formatMysqlTable(displayRows, fields, {
+        maxRows: maxRowsResolved,
+        maxValueBytes,
+        truncated,
+      }) + '\n');
+    }
+
+    process.stderr.write(`✓ ${rows.length} 行${truncated ? '（已截断）' : ''}，${elapsedMs}ms\n`);
+  } finally {
+    // 永远 ROLLBACK，不发 COMMIT（防御性，确保不留事务）
+    await safeRollback(conn);
+    await safeClose(conn);
+  }
+}
+
+main().catch(e => {
+  if (e instanceof CliError || e instanceof ReadonlyError || e instanceof ConfigError) {
+    process.stderr.write('✗ ' + e.message + '\n');
+  } else {
+    process.stderr.write('✗ ' + safeMessage(e) + '\n');
+  }
+  process.exit(1);
+});

package/skills/db-query/scripts/redis-query.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Redis 只读查询入口
+ * 编排流程：CLI 解析 → 命令白名单校验 → 建连 → sendCommand → 输出 → 关闭
+ * 安全要点：db 只通过连接配置选择（不开放 SELECT 命令）；
+ *          客户端 timer 超时 destroy socket；
+ *          Redis ACL 只读用户是服务端最终边界
+ */
+
+const { createClient } = require('redis');
+
+// ── 内部模块 ──
+const { parseCli, CliError } = require('./lib/cli');
+const { loadEnvFile, resolveEnv, resolveEnvNumber, ConfigError, sanitizeTarget, safeMessage, buildTlsOptions } = require('./lib/config');
+const { validateRedisCommand, RedisReadonlyError } = require('./lib/redis-readonly');
+const { formatRedisTable, formatJson } = require('./lib/output');
+
+// ── CLI 参数规格 ──
+const REDIS_SPEC = {
+  host:              { type: 'string', default: '127.0.0.1' },
+  port:              { type: 'integer', default: 6379, min: 1, max: 65535 },
+  user:              { type: 'string', default: 'default' },
+  password:          { type: 'string', default: undefined },
+  db:                { type: 'integer', default: 0, min: 0, max: 15 },
+  tls:               { type: 'boolean', default: false },
+  'ca-file':         { type: 'string', default: undefined },
+  'connect-timeout-ms': { type: 'integer', default: 5000, min: 1000, max: 30000 },
+  'timeout-ms':      { type: 'integer', default: 10000, min: 1000, max: 60000 },
+  'max-items':       { type: 'integer', default: 200, min: 1, max: 5000 },
+  'max-value-bytes': { type: 'integer', default: 4096, min: 256, max: 1048576 },
+  format:            { type: 'string', default: 'table', choices: ['table', 'json'] },
+  'env-file':        { type: 'string', default: undefined },
+  'validate-only':   { type: 'boolean', default: false },
+  'allow-unbounded': { type: 'boolean', default: false },
+};
+
+const ENV_PREFIX = 'DB_QUERY_REDIS_';
+
+// ── 主函数 ──
+async function main() {
+  const { options, rest } = parseCli(process.argv.slice(2), REDIS_SPEC);
+
+  // -- 后面必须是 Redis 命令
+  if (rest.length === 0) {
+    throw new CliError('必须在 -- 之后指定 Redis 命令（如 -- GET key）');
+  }
+
+  // 命令白名单校验（在任何连接操作之前）
+  const validated = validateRedisCommand(rest, {
+    maxItems: options.maxItems,
+    allowUnbounded: options['allow-unbounded'],
+  });
+
+  // --validate-only：纯离线校验，不建连
+  if (options['validate-only']) {
+    process.stderr.write(`✓ 命令校验通过: ${validated.command} ${validated.args.join(' ')}\n`);
+    process.stderr.write(`输出形状: ${validated.shape}${validated.unbounded ? ' (无界)' : ''}\n`);
+    return;
+  }
+
+  // env 文件加载
+  const envPairs = loadEnvFile(options['env-file']);
+
+  // 合并环境变量覆盖（统一用 resolveEnvNumber 做边界校验，防 env 文件绕过硬上限）
+  const host = resolveEnv(envPairs, ENV_PREFIX + 'HOST', options.host);
+  const port = resolveEnvNumber(envPairs, ENV_PREFIX + 'PORT', options.port, { min: 1, max: 65535 });
+  const user = resolveEnv(envPairs, ENV_PREFIX + 'USER', options.user);
+  const password = resolveEnv(envPairs, ENV_PREFIX + 'PASSWORD', options.password);
+  const db = resolveEnvNumber(envPairs, ENV_PREFIX + 'DB', options.db, { min: 0, max: 15 });
+  const maxItems = resolveEnvNumber(envPairs, ENV_PREFIX + 'MAX_ITEMS', options.maxItems, { min: 1, max: 5000 });
+  const maxItemsResolved = maxItems;
+  const maxValueBytes = resolveEnvNumber(envPairs, 'DB_QUERY_MAX_VALUE_BYTES', options['max-value-bytes'], { min: 256, max: 1048576 });
+  const maxValueBytesResolved = maxValueBytes;
+  const timeoutMs = resolveEnvNumber(envPairs, ENV_PREFIX + 'TIMEOUT_MS', options['timeout-ms'], { min: 1000, max: 60000 });
+  const timeoutMsResolved = timeoutMs;
+  const connectTimeoutMs = resolveEnvNumber(envPairs, ENV_PREFIX + 'CONNECT_TIMEOUT_MS', options['connect-timeout-ms'], { min: 1000, max: 30000 });
+  const connectTimeoutMsResolved = connectTimeoutMs;
+
+  // 打印脱敏目标
+  const target = sanitizeTarget({ host, port, user, database: db });
+  process.stderr.write(`→ Redis ${target}\n`);
+
+  // 构建 node-redis v4 客户端
+  const clientConfig = {
+    socket: {
+      host,
+      port,
+      connectTimeout: connectTimeoutMs,
+      // TLS
+      ...(options.tls || options['ca-file']
+        ? { tls: buildTlsOptions(options['ca-file']) || { rejectUnauthorized: true } }
+        : {}),
+    },
+    database: db,
+    password: password || undefined,
+    username: user,
+    // 保留 Buffer 返回，避免自动字符串化丢二进制
+    returnBuffers: true,
+  };
+
+  const client = createClient(clientConfig);
+
+  // 超时定时器（connect + sendCommand 总超时）
+  const timer = setTimeout(() => {
+    client.destroy();
+    // 不直接 reject（Promise 可能已 settle），通过 error 事件处理
+  }, timeoutMsResolved);
+
+  try {
+    await client.connect();
+
+    // sendCommand 以数组形式传参，绝不拼接后 split（防止参数含空格被截断）
+    const cmdArgs = [validated.command, ...validated.args.map(String)];
+    const startMs = Date.now();
+    const result = await client.sendCommand(cmdArgs);
+    const elapsedMs = Date.now() - startMs;
+
+    clearTimeout(timer);
+
+    // 判断截断
+    let count = 0;
+    let truncated = false;
+    if (Array.isArray(result)) {
+      count = result.length;
+      truncated = count > maxItemsResolved;
+    } else {
+      count = 1;
+    }
+
+    if (options.format === 'json') {
+      // JSON envelope 写 stdout
+      process.stdout.write(JSON.stringify({
+        source: 'redis',
+        target,
+        elapsedMs,
+        count: truncated ? maxItemsResolved : count,
+        truncated,
+        // Buffer → base64 以确保 JSON 安全
+        result: sanitizeForJson(result),
+      }, null, 2) + '\n');
+    } else {
+      process.stdout.write(formatRedisTable(result, {
+        shape: validated.shape,
+        command: validated.command,
+        maxItems: maxItemsResolved,
+        maxValueBytes: maxValueBytesResolved,
+      }) + '\n');
+    }
+
+    process.stderr.write(`✓ ${count} 条${truncated ? '（已截断）' : ''}，${elapsedMs}ms\n`);
+  } catch (e) {
+    clearTimeout(timer);
+    throw e;
+  } finally {
+    try { await client.quit(); } catch (_) { /* 忽略关闭错误 */ }
+  }
+}
+
+/** 递归将 Buffer 转为 base64，确保 JSON 安全 */
+function sanitizeForJson(val) {
+  if (Buffer.isBuffer(val)) return val.toString('base64');
+  if (Array.isArray(val)) return val.map(sanitizeForJson);
+  if (val && typeof val === 'object' && val.constructor === Object) {
+    const out = {};
+    for (const k of Object.keys(val)) out[k] = sanitizeForJson(val[k]);
+    return out;
+  }
+  return val;
+}
+
+main().catch(e => {
+  // 校验类/配置类错误直接显示消息（不是连接错误，不需要脱敏）
+  if (e instanceof CliError || e instanceof RedisReadonlyError || e instanceof ConfigError) {
+    process.stderr.write('✗ ' + e.message + '\n');
+  } else {
+    process.stderr.write('✗ ' + safeMessage(e) + '\n');
+  }
+  process.exit(1);
+});

package/skills/db-query/scripts/setup.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# db-query 技能一键环境检查 + 安装 + 测试
+# 幂等：依赖已装则跳过 npm ci
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$SCRIPT_DIR"
+
+# ── Node / npm 版本检查 ──
+if ! command -v node &>/dev/null; then
+  echo "✗ 未找到 node，需要 Node.js >= 18"
+  exit 1
+fi
+
+NODE_MAJOR=$(node -e "process.stdout.write(String(process.versions.node.split('.')[0]))")
+if [ "$NODE_MAJOR" -lt 18 ]; then
+  echo "✗ Node.js 版本 $(node -v) 低于最低要求 18"
+  exit 1
+fi
+
+if ! command -v npm &>/dev/null; then
+  echo "✗ 未找到 npm"
+  exit 1
+fi
+
+echo "Node $(node -v) ✓  npm $(npm -v) ✓"
+
+# ── 幂等安装运行时依赖 ──
+# 已有 node_modules 时 npm ci 仍会检查一致性，幂等安全
+if [ -d node_modules ]; then
+  echo "依赖已存在，跳过安装（删除 node_modules 可强制重装）"
+else
+  echo "安装运行时依赖（mysql2 redis dotenv）..."
+  if [ -f package-lock.json ]; then
+    npm ci --omit=dev --no-audit --no-fund
+  else
+    npm install --omit=dev --no-audit --no-fund
+  fi
+  echo "依赖安装 ✓"
+fi
+
+# ── 运行测试 ──
+echo "运行测试..."
+if node --test tests/*.test.js 2>/dev/null; then
+  echo "全部测试通过 ✓"
+else
+  echo "⚠ 未找到测试文件或测试未通过（首次部署无测试属正常）"
+fi
+
+echo "db-query 环境就绪 ✓"

package/skills/git-commit-message/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: git-commit-message
+description: Generate convention-compliant Git commit messages. Trigger whenever the intent is to produce commit text (commit message/description), including "generate the commit description/message" after a batch of changes — even without the word "commit". Text only; never commits or pushes.
+---
+
+<!-- [2026-09-05]-[default output to English unless project rules/user explicitly request Chinese; generic examples]-[generated messages follow this default] -->
+<!-- [2026-10-01]-[Language section: honor a [SWITCHMAN:LANG] system-prompt line over the English default]-[aligns with the host-side language-preference layer] -->
+# Git Commit Message Generation
+
+Core rule: **deliver text only; never run `git add` / `git commit` / `git push`**.
+
+Language: **English by default**. Use the project's configured language when the project's rules (AGENTS.md etc.) explicitly specify one, or when the user explicitly requests it.
+
+## Flow
+
+### 1. Confirm the task ID (always first)
+
+- Not provided → ask once ("task ID for this commit?"); never invent it
+- User explicitly declines → omit the ID (only exception); don't re-ask within the same session
+
+### 2. Analyze changes
+
+Run as needed, not mechanically: `git status` (files changed), `git diff` / `git diff --cached` (content), `git log --oneline -5` (repo style). Reuse this conversation's context when available to run fewer commands.
+
+### 3. Generate the message
+
+**Subject** (concise, one line): `<type>(<task-id>): <what was done>`; without ID `<type>: <what was done>`. State the result, not the process; no trailing period.
+
+type: `feat` / `fix` / `refactor` / `docs` / `test` / `perf` / `style` / `chore`.
+
+**Body**: numbered points, usually 2~4 (1 if trivial); one key change per point, no diff restatement.
+
+Example:
+
+```
+refactor(1024): Extract config parsing into loader module
+
+1. Move inline parsing logic into config/loader.ts
+2. Add validation for missing required fields
+3. Extend tests to cover the new module
+```
+
+### 4. Stop after delivery
+
+Present the message and stop; don't ask "want me to commit?". Commit/push only on explicit request.
+
+## Language
+
+English by default; use the project's configured language when a `[SWITCHMAN:LANG]` line in the system prompt specifies one, or when the user explicitly requests it.

package/skills/requirement-docs/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: requirement-docs
+description: Unified spec for technical docs — requirements analysis, PRD, design, architecture, API design, tech plan, dev plan. Trigger before drafting or reorganizing any such doc; archive to docs/requirements-and-design/ with unified naming. English by default.
+---
+
+<!-- [2026-09-05]-[default output to English unless project rules/user explicitly request Chinese; generic examples]-[generated docs follow this default] -->
+<!-- [2026-10-01]-[Language section: honor a [SWITCHMAN:LANG] system-prompt line over the English default]-[aligns with the host-side language-preference layer] -->
+# Requirements & Design Doc Spec
+
+Goal: centralized archiving, unified naming, consistent structure; understand existing code before proposing solutions.
+
+Language: **English by default** (keep technical terms as-is). Use the project's configured language when the project's rules (AGENTS.md etc.) explicitly specify one, or when the user explicitly requests it.
+
+## 1. Flow (every time)
+
+1. Locate repo root, `mkdir -p docs/requirements-and-design/` (reuse the repo's existing archive dir if present); scan existing files to avoid name clashes and style drift.
+2. Name as `yyyy-mm-dd-<module>-<type>.md`: today's date; module in kebab-case; type word in the doc's language — `requirements` / `PRD` / `design` / `architecture` / `api-design` / `tech-plan` / `dev-plan` (Chinese docs: 需求分析/PRD/设计/架构设计/接口设计/技术方案/开发计划).
+   E.g. `docs/requirements-and-design/2026-09-05-config-loader-design.md`
+3. Research first: read related code, `docs/`, `README`, `AGENTS.md`, key entities/services before writing.
+4. Read `references/templates.md` (mandatory) to pick a skeleton; it defines structure only — render section titles and content in the output language. Self-check after writing (date, type word, section style, [Decided]/[Pending] markers, appendix), then report the file path to the user.
+
+## 2. Core principles (legacy-system methodology)
+
+1. **Evidence-backed current-state analysis**: trace call chains from entry points (Controller/API/CLI) to core logic with `file:line`; list reusable assets and reference implementations; call out existing pitfalls (swallowed exceptions, hardcoding, etc.). No empty "the system currently has X" statements.
+2. **Current state → gaps → solution**: current-state analysis first, then a gap table (numbered D1/D2…, current vs required); the solution references gap IDs point by point.
+3. **Honest [Decided]/[Pending] split** (Chinese: 【已定】/【待定】): confirmed decisions in a quote block at the top with confirmation dates; open questions in their own section, each with a recommended lean; every risk carries a mitigation. Never present pending as decided.
+4. **Field-level clarity & appendix**: for key fields state exactly which entity/field they come from; expand ambiguous spots with a comparison and a recommendation; end with a file:line quick-reference table.
+
+## 3. Writing rules
+
+1. Wrap code, paths, field names in backticks.
+2. Prefer mermaid or indented code blocks for call chains/sequences/flows; no external images.
+3. Give reasons for decisions, not just conclusions.
+4. When citing `file:line`, include the method name/context to survive line drift.
+
+## Language
+
+English by default; use the project's configured language when a `[SWITCHMAN:LANG]` line in the system prompt specifies one, or when the user explicitly requests it.