opencode-core-rules-injector 1.2.3 → 1.2.5

package/README.md

@@ -1,79 +1,110 @@
 # opencode-core-rules-injector
 
-OpenCode 插件：在每次 LLM 调用前注入核心规则，确保模型始终遵守你的工作流和偏好。
+OpenCode 插件：在每次 LLM 调用前持续注入核心规则，降低主 Agent 长时间自动运行时偏离工作流的风险。
 
-## 作用
+## 目标
 
-OpenCode 在长时间自动执行（如 5 小时、100 个任务）时，模型容易忘记用户制定的规则。已有的方式（AGENTS.md、opencode.json instructions）只在会话启动时读取一次，无法防止长任务中的注意力漂移。
+`AGENTS.md` 和 `instructions` 适合会话启动时加载规则，但它们不是每轮 LLM 调用前的动态注入机制。本插件的目标是在主 Agent 连续执行工具调用、调度子 Agent、长时间自动推进任务时，仍然让模型持续看到 `core-rules.md`。
 
-这个插件在**每次 LLM 调用前**把 `~/.config/opencode/core-rules.md` 的内容注入到 system prompt 中，让模型每轮都能看到规则，确保始终如一地遵守。
+## 注入路径
 
-## 实现方法
+主路径：`experimental.chat.system.transform`
 
-1. 利用 OpenCode 的 `experimental.chat.system.transform` 钩子，在每个 LLM 调用前修改 system prompt
-2. 读取 `~/.config/opencode/core-rules.md` 的内容并追加到 system prompt 尾部
-3. 带 mtime 缓存，文件无变化时不重复读盘
-4. 首次安装时自动创建 `~/.config/opencode/core-rules.md`（含默认工作流）
-5. 通过 `postinstall` 脚本自动注册到 `opencode.jsonc/opencode.json` 的 `"plugin"` 数组
+- 每次 LLM 调用前触发。
+- 将 `core-rules.md` 追加到 system prompt 数组。
+- 这是长任务自动运行期间的核心保障。
 
-三层规则保障：
+辅助路径：`chat.message`
 
-| 层 | 生效时机 | 覆盖范围 |
-|---|---|---|
-| **AGENTS.md**（核心指令+工作流） | 会话启动时 | 主 Agent + 所有子 Agent |
-| **core-rules.md**（插件注入） | 每次 LLM 调用前 | 主 Agent |
-| **AGENTS.md 上下文**（ctx7 等） | 会话启动时 | 主 Agent + 所有子 Agent |
+- 用户每次发送新消息时触发。
+- 将 `core-rules.md` 插入到用户消息 parts 头部。
+- 这是用户消息级兜底，不替代主路径。
+
+不使用：`chat.params`
+
+- OpenCode 当前源码中 `chat.params` 只能修改 temperature、topP、topK、maxOutputTokens 和 options。
+- 它不能修改 system prompt、messages 或 message parts。
+
+## 运行态目录
+
+```text
+~/.config/opencode/plugins/opencode-core-rules-injector/
+├── config.toml
+├── core-rules.md
+└── logs/
+    └── injector-YYYY-MM-DD.log
+```
+
+`config.toml` 默认内容：
+
+```toml
+[git]
+user_name = "liumenglife"
+user_email = "liumenglife@163.com"
+default_branch = "main"
+
+[logging]
+daily_rotation = true
+```
+
+## 日志状态
+
+日志按天滚动，写入：
+
+```text
+~/.config/opencode/plugins/opencode-core-rules-injector/logs/injector-YYYY-MM-DD.log
+```
+
+状态码：
+
+| 状态 | 含义 |
+|---|---|
+| `BOTH_OK` | 主路径和辅助路径都成功；这是状态计算能力和未来聚合日志保留状态，当前单条 hook 日志通常不会出现 |
+| `PRIMARY_ONLY` | 主路径成功，辅助路径失败或未触发；表示主路径正在工作，长任务保障成立 |
+| `FALLBACK_ONLY` | 主路径失败或未触发，仅辅助路径成功；只能说明用户消息级兜底生效，不代表长任务保障成立 |
+| `BOTH_FAILED` | 主路径和辅助路径都失败或未触发 |
+
+当前实现按 hook 写单条日志，不会在同一条日志里同时执行两条路径：`experimental.chat.system.transform` 日志中的 fallback 固定为 `skipped`，主路径成功时通常记录为 `PRIMARY_ONLY`；`chat.message` 日志中的 primary 固定为 `skipped`，辅助路径成功时通常记录为 `FALLBACK_ONLY`。因此不需要看到 `BOTH_OK` 才算正常，长任务判断重点看 `experimental.chat.system.transform` 日志是否出现 `PRIMARY_ONLY`。
+
+示例：
+
+```text
+2026-06-13T10:00:00.000Z session=ab12cd34 hook=experimental.chat.system.transform status=PRIMARY_ONLY primary=ok(chars=2451,mtime=1780000000000) fallback=skipped(no_user_message_this_turn)
+```
 
 ## 安装
 
 ```bash
-# 使用 bun（推荐，更快），--trust 确保 postinstall 脚本执行
 bun install -g opencode-core-rules-injector --trust
+```
+
+或：
 
-# 或使用 npm
+```bash
 npm install -g opencode-core-rules-injector
 ```
 
-安装后重启 OpenCode 即可生效。`postinstall` 会自动完成以下操作：
+安装后重启 OpenCode。OpenCode 配置不会热重载。
 
-- 将 `"opencode-core-rules-injector"` 添加到 `~/.config/opencode/opencode.jsonc` 或 `opencode.json` 的 `"plugin"` 数组
-- 创建 `~/.config/opencode/core-rules.md`（含默认的语言、工具偏好和工作流规则）
+## 迁移
 
-## 自定义规则
+安装或升级时会自动迁移：
 
-编辑 `~/.config/opencode/core-rules.md`，修改立即生效，无需重启：
+- `~/.config/opencode/core-rules.md` → `~/.config/opencode/plugins/opencode-core-rules-injector/core-rules.md`
+- `~/.config/opencode-agent/config.toml` → `~/.config/opencode/plugins/opencode-core-rules-injector/config.toml`
 
-```markdown
-## 语言
-始终使用简体中文输出，包括工具调用描述、思考过程等全部内容。
+如果新路径文件已存在，安装脚本不会覆盖。
 
-## 工具偏好
-- **文件内容搜索**: `rg` 而非 `grep`
-- **文件名搜索**: `fd` 而非 `find`
-- **内容替换**: `sd` 而非 `sed`
-- **JSON 处理**: `jq`
-- **HTTP 请求**: `httpie` 而非 `curl`
-- **文件查看**: `bat` 而非 `cat`
-- **包管理**: Python 用 `uv` 而非 `pip3`
-- Rust 三板斧：`rg` + `fd` + `sd`
+## 验证
 
-## 工作流
-...
+```bash
+npm test
 ```
 
-## 更新
+运行 OpenCode 后检查日志：
 
 ```bash
-bun install -g opencode-core-rules-injector@latest --trust
-# 或
-npm install -g opencode-core-rules-injector@latest
+rg "status=" ~/.config/opencode/plugins/opencode-core-rules-injector/logs
 ```
 
-## 发布历史
-
-| 版本 | 说明 |
-|---|---|
-| 1.0.0 | 基础插件：每轮注入 core-rules.md |
-| 1.0.1 | 新增 postinstall 自动注册 |
-| 1.1.0 | 添加完整工作流规则 |
-| 1.1.3 | 拆分 Specs/Plans 目录，明确人工确认边界 |
+`PRIMARY_ONLY` 表示主路径正在工作，长任务注入保障成立。

package/core-rules.md

@@ -54,7 +54,7 @@
 - QA 审核
 
 ## 注入确认
-本段核心规则被注入后，你的第一条输出必须以绿色文字开头。输出内容为：已收到核心规则注入，开始执行工作流，其中  和  必须是实际的 ESC 控制字符（ASCII 27，单字节），而非写成纯文本 "backslash 0 3 3" 五个字符。然后才能进行思考、调用工具或进行其他操作。
+本段核心规则被注入后，你的第一条输出必须以**已收到核心规则注入，开始执行工作流**开头（注意加粗渲染，须用实际 Markdown ** 包裹），然后才能进行思考、调用工具或进行其他操作。
 
 ## 通信规范
 所有代理（含主代理、子代理）的评审、测试、审核结论必须基于事实表达：

package/index.js

@@ -1,43 +1,39 @@
-import { readFileSync, statSync, existsSync, mkdirSync, writeFileSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const CONFIG_DIR = join(process.env.HOME || process.env.USERPROFILE, '.config', 'opencode');
-const RULES_FILE = join(CONFIG_DIR, 'core-rules.md');
-const DEFAULT_RULES = join(__dirname, 'core-rules.md');
-
-function ensureDefaultRules() {
-  if (existsSync(RULES_FILE)) return;
-  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
-  if (existsSync(DEFAULT_RULES)) {
-    writeFileSync(RULES_FILE, readFileSync(DEFAULT_RULES, 'utf-8'));
-  }
-}
+import { ensureRuntimeFiles, createRuleLoader } from './src/runtime.js';
+import { createLogger } from './src/logging.js';
+import { injectPrimarySystem, injectFallbackMessage } from './src/injector.js';
 
-let rulesCache = null;
-let rulesMtime = 0;
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_RULES_FILE = join(__dirname, 'core-rules.md');
 
-function loadRules() {
-  try {
-    if (!existsSync(RULES_FILE)) return '';
-    const { mtimeMs } = statSync(RULES_FILE);
-    if (rulesCache && mtimeMs === rulesMtime) return rulesCache;
-    rulesMtime = mtimeMs;
-    rulesCache = readFileSync(RULES_FILE, 'utf-8').trim();
-    return rulesCache;
-  } catch {
-    return '';
-  }
+function readDefaultRules() {
+  return readFileSync(DEFAULT_RULES_FILE, 'utf8');
 }
 
-ensureDefaultRules();
+export const CoreRulesInjector = async (options = {}) => {
+  const paths = ensureRuntimeFiles({ home: options.home, defaultRules: readDefaultRules() });
+  const loadRules = options.loadRules ?? createRuleLoader(paths.rulesFile);
+  const logger = options.logger ?? createLogger({ logsDir: paths.logsDir });
 
-export const CoreRulesInjector = async () => {
   return {
-    'experimental.chat.system.transform': async (_input, output) => {
-      const rules = loadRules();
-      if (rules) output.system.push(rules);
+    'experimental.chat.system.transform': async (input, output) => {
+      try {
+        injectPrimarySystem({ input, output, loadRules, logger });
+      } catch {
+        // 兜底保护 OpenCode 主流程；正常错误日志由 injector 内部处理。
+      }
+    },
+    'chat.message': async (input, output) => {
+      try {
+        injectFallbackMessage({ input, output, loadRules, logger });
+      } catch {
+        // 兜底保护 OpenCode 主流程；正常错误日志由 injector 内部处理。
+      }
     },
   };
 };
+
+export default CoreRulesInjector;

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "opencode-core-rules-injector",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "OpenCode plugin: injects core rules into every LLM call",
   "type": "module",
   "main": "index.js",
-  "files": ["index.js", "core-rules.md", "postinstall.mjs"],
+  "files": ["index.js", "src", "core-rules.md", "postinstall.mjs", "README.md"],
   "keywords": ["opencode", "plugin", "rules"],
   "license": "MIT",
   "scripts": {
-    "postinstall": "node postinstall.mjs"
-  }
+    "postinstall": "node postinstall.mjs",
+    "test": "node --test"
+  },
+  "devDependencies": {}
 }

package/postinstall.mjs

@@ -1,45 +1,287 @@
-import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { ensureRuntimeFiles } from './src/runtime.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const HOME = process.env.HOME || process.env.USERPROFILE;
-const CONFIG_DIR = join(HOME, '.config', 'opencode');
 const PLUGIN_NAME = 'opencode-core-rules-injector';
 
-const candidates = ['opencode.jsonc', 'opencode.json'];
-let configFile = null;
-for (const name of candidates) {
-  const p = join(CONFIG_DIR, name);
-  if (existsSync(p)) { configFile = p; break; }
-}
-
-if (configFile) {
-  let content = readFileSync(configFile, 'utf-8');
-  if (!content.includes(PLUGIN_NAME)) {
-    content = content.replace(
-      /("plugin"\s*:\s*\[)([^\]]*)(\])/,
-      (_, start, items, end) => {
-        const trimmed = items.trim();
-        const sep = trimmed ? ', ' : '';
-        return `${start}${items}${sep}"${PLUGIN_NAME}"${end}`;
+function homeDir(explicitHome) {
+  const home = explicitHome || process.env.HOME || process.env.USERPROFILE;
+  if (!home) throw new Error('HOME or USERPROFILE is required');
+  return home;
+}
+
+function configDir(home) {
+  return join(home, '.config', 'opencode');
+}
+
+function stripJsonComments(content) {
+  let result = '';
+  let inString = false;
+  let escaped = false;
+
+  for (let i = 0; i < content.length; i += 1) {
+    const char = content[i];
+    const next = content[i + 1];
+
+    if (inString) {
+      result += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      result += char;
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      while (i < content.length && content[i] !== '\n') i += 1;
+      result += '\n';
+      continue;
+    }
+
+    if (char === '/' && next === '*') {
+      i += 2;
+      while (i < content.length && !(content[i] === '*' && content[i + 1] === '/')) {
+        if (content[i] === '\n') result += '\n';
+        i += 1;
+      }
+      i += 1;
+      continue;
+    }
+
+    result += char;
+  }
+
+  return result;
+}
+
+function stripTrailingCommas(content) {
+  return content.replace(/,\s*([}\]])/g, '$1');
+}
+
+function parseConfig(content) {
+  return JSON.parse(stripTrailingCommas(stripJsonComments(content)));
+}
+
+function findMatchingBracket(content, openIndex) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  let lineComment = false;
+  let blockComment = false;
+
+  for (let i = openIndex; i < content.length; i += 1) {
+    const char = content[i];
+    const next = content[i + 1];
+
+    if (lineComment) {
+      if (char === '\n') lineComment = false;
+      continue;
+    }
+
+    if (blockComment) {
+      if (char === '*' && next === '/') {
+        blockComment = false;
+        i += 1;
+      }
+      continue;
+    }
+
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      lineComment = true;
+      i += 1;
+      continue;
+    }
+
+    if (char === '/' && next === '*') {
+      blockComment = true;
+      i += 1;
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+
+    if (char === '[') depth += 1;
+    if (char === ']') {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+
+  return -1;
+}
+
+function findPluginArray(content) {
+  let inString = false;
+  let escaped = false;
+  let lineComment = false;
+  let blockComment = false;
+
+  for (let i = 0; i < content.length; i += 1) {
+    const char = content[i];
+    const next = content[i + 1];
+
+    if (lineComment) {
+      if (char === '\n') lineComment = false;
+      continue;
+    }
+
+    if (blockComment) {
+      if (char === '*' && next === '/') {
+        blockComment = false;
+        i += 1;
+      }
+      continue;
+    }
+
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
       }
-    );
-    writeFileSync(configFile, content, 'utf-8');
-    console.log(`[postinstall] Added "${PLUGIN_NAME}" to ${configFile}`);
-  } else {
-    console.log(`[postinstall] "${PLUGIN_NAME}" already in ${configFile}`);
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      lineComment = true;
+      i += 1;
+      continue;
+    }
+
+    if (char === '/' && next === '*') {
+      blockComment = true;
+      i += 1;
+      continue;
+    }
+
+    if (content.startsWith('"plugin"', i)) {
+      let j = i + '"plugin"'.length;
+      while (/\s/.test(content[j])) j += 1;
+      if (content[j] !== ':') continue;
+      j += 1;
+      while (/\s/.test(content[j])) j += 1;
+      if (content[j] !== '[') continue;
+      const end = findMatchingBracket(content, j);
+      if (end !== -1) return { start: j, end };
+    }
+
+    if (char === '"') inString = true;
   }
-} else {
-  const fallback = join(CONFIG_DIR, 'opencode.json');
-  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
-  writeFileSync(fallback, JSON.stringify({ plugin: [PLUGIN_NAME] }, null, 2), 'utf-8');
-  console.log(`[postinstall] Created ${fallback} with "${PLUGIN_NAME}"`);
-}
-
-const rulesFile = join(CONFIG_DIR, 'core-rules.md');
-const defaultRules = join(__dirname, 'core-rules.md');
-if (!existsSync(rulesFile) && existsSync(defaultRules)) {
-  writeFileSync(rulesFile, readFileSync(defaultRules, 'utf-8'));
-  console.log(`[postinstall] Created ${rulesFile}`);
+
+  return null;
+}
+
+function indentationBefore(content, index) {
+  const lineStart = content.lastIndexOf('\n', index) + 1;
+  const match = content.slice(lineStart, index).match(/^\s*/);
+  return match ? match[0] : '';
+}
+
+function formatPluginArray(content, range, plugins) {
+  const arrayText = content.slice(range.start, range.end + 1);
+  if (!arrayText.includes('\n')) return `[${plugins.map((plugin) => JSON.stringify(plugin)).join(', ')}]`;
+
+  const baseIndent = indentationBefore(content, range.start);
+  const itemIndent = `${baseIndent}  `;
+  const lines = plugins.map((plugin, index) => {
+    const comma = index === plugins.length - 1 ? '' : ',';
+    return `${itemIndent}${JSON.stringify(plugin)}${comma}`;
+  });
+  return `[\n${lines.join('\n')}\n${baseIndent}]`;
+}
+
+function addPluginProperty(content) {
+  const closeIndex = content.lastIndexOf('}');
+  if (closeIndex === -1) return content;
+
+  const beforeClose = content.slice(0, closeIndex);
+  const afterClose = content.slice(closeIndex);
+  const hasFields = Object.keys(parseConfig(content)).length > 0;
+  const baseIndent = indentationBefore(content, closeIndex);
+  const itemIndent = `${baseIndent}  `;
+
+  if (!content.includes('\n')) {
+    const comma = hasFields ? ', ' : '';
+    return `${beforeClose}${comma}"plugin": ["${PLUGIN_NAME}"]${afterClose}`;
+  }
+
+  const trimmedBeforeClose = beforeClose.replace(/[\s,]*$/, '');
+  const comma = hasFields ? ',' : '';
+  return `${trimmedBeforeClose}${comma}\n${itemIndent}"plugin": ["${PLUGIN_NAME}"]\n${afterClose}`;
+}
+
+function appendPlugin(content) {
+  const cfg = parseConfig(content);
+  if (!Array.isArray(cfg.plugin)) cfg.plugin = [];
+  if (cfg.plugin.includes(PLUGIN_NAME)) return content;
+
+  const plugins = [...cfg.plugin, PLUGIN_NAME];
+  const range = findPluginArray(content);
+  if (!range) return addPluginProperty(content);
+
+  return `${content.slice(0, range.start)}${formatPluginArray(content, range, plugins)}${content.slice(range.end + 1)}`;
+}
+
+export function ensureOpenCodeConfig(explicitHome) {
+  const home = homeDir(explicitHome);
+  const dir = configDir(home);
+  mkdirSync(dir, { recursive: true });
+  const candidates = [join(dir, 'opencode.jsonc'), join(dir, 'opencode.json')];
+  const configFile = candidates.find((file) => existsSync(file)) || candidates[1];
+
+  if (!existsSync(configFile)) {
+    writeFileSync(configFile, JSON.stringify({ plugin: [PLUGIN_NAME] }, null, 2), 'utf8');
+    return configFile;
+  }
+
+  const original = readFileSync(configFile, 'utf8');
+  let next;
+  try {
+    next = appendPlugin(original);
+  } catch (error) {
+    console.warn(`[postinstall] Warning: could not update OpenCode config ${configFile}: ${error.message}`);
+    return configFile;
+  }
+  if (next !== original) writeFileSync(configFile, next, 'utf8');
+  return configFile;
+}
+
+export function runPostinstall(explicitHome) {
+  const defaultRules = readFileSync(join(__dirname, 'core-rules.md'), 'utf8');
+  const paths = ensureRuntimeFiles({ home: explicitHome, defaultRules });
+  const configFile = ensureOpenCodeConfig(explicitHome);
+  console.log(`[postinstall] Runtime directory: ${paths.runtimeDir}`);
+  console.log(`[postinstall] OpenCode config: ${configFile}`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  runPostinstall();
 }

package/src/injector.js

@@ -0,0 +1,105 @@
+import { statusFromResults } from './logging.js';
+
+const RULES_START = '<opencode-core-rules-injector>';
+const RULES_END = '</opencode-core-rules-injector>';
+
+function okDetail(ruleInfo) {
+  return `ok(chars=${ruleInfo.chars},mtime=${ruleInfo.mtimeMs})`;
+}
+
+function errorDetail(reason) {
+  return `error(${reason})`;
+}
+
+function wrappedRules(ruleInfo) {
+  return `${RULES_START}\n${ruleInfo.text}\n${RULES_END}`;
+}
+
+function fallbackPartMetadata(input, output) {
+  const firstPart = output.parts[0];
+  const sessionID = firstPart?.sessionID || output.message?.sessionID || input?.sessionID;
+  const messageID = firstPart?.messageID || output.message?.messageID || output.message?.id || input?.messageID;
+
+  if (typeof sessionID !== 'string' || typeof messageID !== 'string') {
+    throw new Error('part_metadata_missing');
+  }
+
+  return {
+    id: `prt_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+    sessionID,
+    messageID,
+  };
+}
+
+export function injectPrimarySystem({ input, output, loadRules, logger }) {
+  let primary = 'error';
+  let primaryDetail = '';
+  let error = '';
+
+  try {
+    if (!Array.isArray(output.system)) throw new Error('output.system_missing');
+    const ruleInfo = loadRules();
+    if (!ruleInfo.text) throw new Error('rules_file_empty');
+    if (output.system.some((part) => typeof part === 'string' && part.includes(RULES_START))) {
+      primary = 'skipped';
+      primaryDetail = 'skipped(already_injected)';
+    } else {
+      output.system.push(wrappedRules(ruleInfo));
+      primary = 'ok';
+      primaryDetail = okDetail(ruleInfo);
+    }
+  } catch (err) {
+    error = err instanceof Error ? err.message : String(err);
+    primaryDetail = errorDetail(error);
+  }
+
+  const fallback = 'skipped';
+  const fallbackDetail = 'skipped(no_user_message_this_turn)';
+  const status = statusFromResults({ primary, fallback });
+  logger.write({
+    sessionID: input?.sessionID,
+    hook: 'experimental.chat.system.transform',
+    status,
+    primary: primaryDetail,
+    fallback: fallbackDetail,
+    error,
+  });
+  return { ok: primary === 'ok', status };
+}
+
+export function injectFallbackMessage({ input, output, loadRules, logger }) {
+  let fallback = 'error';
+  let fallbackDetail = '';
+  let error = '';
+
+  try {
+    if (!Array.isArray(output.parts)) throw new Error('output.parts_missing');
+    const ruleInfo = loadRules();
+    if (!ruleInfo.text) throw new Error('rules_file_empty');
+    if (output.parts.some((part) => part?.type === 'text' && part.text?.includes(RULES_START))) {
+      fallback = 'skipped';
+      fallbackDetail = 'skipped(already_injected)';
+    } else {
+      const metadata = fallbackPartMetadata(input, output);
+      output.parts.unshift({ ...metadata, type: 'text', text: wrappedRules(ruleInfo) });
+      fallback = 'ok';
+      fallbackDetail = okDetail(ruleInfo);
+    }
+  } catch (err) {
+    error = err instanceof Error ? err.message : String(err);
+    fallbackDetail = errorDetail(error);
+  }
+
+  const primary = 'skipped';
+  const primaryDetail = 'skipped(primary_not_triggered_this_hook)';
+  const status = statusFromResults({ primary, fallback });
+  logger.write({
+    sessionID: input?.sessionID,
+    hook: 'chat.message',
+    status,
+    primary: primaryDetail,
+    fallback: fallbackDetail,
+    error,
+  });
+  return { ok: fallback === 'ok', status };
+}

package/src/logging.js

@@ -0,0 +1,44 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function statusFromResults({ primary, fallback }) {
+  const primaryOk = primary === 'ok';
+  const fallbackOk = fallback === 'ok';
+  if (primaryOk && fallbackOk) return 'BOTH_OK';
+  if (primaryOk) return 'PRIMARY_ONLY';
+  if (fallbackOk) return 'FALLBACK_ONLY';
+  return 'BOTH_FAILED';
+}
+
+function datePart(date) {
+  return date.toISOString().slice(0, 10);
+}
+
+function cleanField(value) {
+  return String(value ?? '').replace(/[\r\n]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function sessionPart(sessionID) {
+  return (cleanField(sessionID) || 'unknown').slice(0, 8);
+}
+
+export function createLogger({ logsDir, now = () => new Date() }) {
+  mkdirSync(logsDir, { recursive: true });
+  return {
+    write(entry) {
+      const date = now();
+      const file = join(logsDir, `injector-${datePart(date)}.log`);
+      const line = [
+        date.toISOString(),
+        `session=${sessionPart(entry.sessionID)}`,
+        `hook=${cleanField(entry.hook)}`,
+        `status=${cleanField(entry.status)}`,
+        `primary=${cleanField(entry.primary)}`,
+        `fallback=${cleanField(entry.fallback)}`,
+        entry.error ? `error=${cleanField(entry.error)}` : '',
+      ].filter(Boolean).join(' ');
+      appendFileSync(file, `${line}\n`, 'utf8');
+      return file;
+    },
+  };
+}

package/src/paths.js

@@ -0,0 +1,26 @@
+import { join } from 'node:path';
+
+export const PLUGIN_DIR_NAME = 'opencode-core-rules-injector';
+
+export function getHome(explicitHome) {
+  const home = explicitHome || process.env.HOME || process.env.USERPROFILE;
+  if (!home) throw new Error('HOME or USERPROFILE is required');
+  return home;
+}
+
+export function getPaths(explicitHome) {
+  const home = getHome(explicitHome);
+  const opencodeDir = join(home, '.config', 'opencode');
+  const runtimeDir = join(opencodeDir, 'plugins', PLUGIN_DIR_NAME);
+  return {
+    home,
+    opencodeDir,
+    runtimeDir,
+    rulesFile: join(runtimeDir, 'core-rules.md'),
+    configFile: join(runtimeDir, 'config.toml'),
+    logsDir: join(runtimeDir, 'logs'),
+    oldRulesFile: join(opencodeDir, 'core-rules.md'),
+    oldAgentConfigDir: join(home, '.config', 'opencode-agent'),
+    oldAgentConfigFile: join(home, '.config', 'opencode-agent', 'config.toml'),
+  };
+}

package/src/runtime.js

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, readdirSync } from 'node:fs';
+import { getPaths } from './paths.js';
+
+export const DEFAULT_CONFIG = `# OpenCode Core Rules Injector runtime config
+
+[git]
+user_name = "liumenglife"
+user_email = "liumenglife@163.com"
+default_branch = "main"
+
+[logging]
+daily_rotation = true
+`;
+
+function moveIfMissing(source, target) {
+  if (existsSync(target) || !existsSync(source)) return false;
+  renameSync(source, target);
+  return true;
+}
+
+function removeIfEmpty(dir) {
+  if (!existsSync(dir)) return;
+  if (readdirSync(dir).length === 0) rmSync(dir, { recursive: true, force: true });
+}
+
+export function ensureRuntimeFiles({ home, defaultRules }) {
+  const paths = getPaths(home);
+  mkdirSync(paths.runtimeDir, { recursive: true });
+  mkdirSync(paths.logsDir, { recursive: true });
+
+  moveIfMissing(paths.oldRulesFile, paths.rulesFile);
+  moveIfMissing(paths.oldAgentConfigFile, paths.configFile);
+
+  if (!existsSync(paths.rulesFile)) writeFileSync(paths.rulesFile, defaultRules, 'utf8');
+  if (!existsSync(paths.configFile)) writeFileSync(paths.configFile, DEFAULT_CONFIG, 'utf8');
+
+  removeIfEmpty(paths.oldAgentConfigDir);
+  return paths;
+}
+
+export function createRuleLoader(rulesFile) {
+  let cached = null;
+  let cachedMtimeNs = 0n;
+  let cachedMtimeMs = 0;
+
+  return function loadRules() {
+    if (!existsSync(rulesFile)) return { text: '', mtimeMs: 0, chars: 0 };
+    const { mtime, mtimeNs } = statSync(rulesFile, { bigint: true });
+    const mtimeMs = mtime.getTime();
+    if (cached !== null && cachedMtimeNs === mtimeNs) {
+      return { text: cached, mtimeMs: cachedMtimeMs, chars: cached.length };
+    }
+    cached = readFileSync(rulesFile, 'utf8').trim();
+    cachedMtimeNs = mtimeNs;
+    cachedMtimeMs = mtimeMs;
+    return { text: cached, mtimeMs, chars: cached.length };
+  };
+}