minimal-agent 0.2.0 → 0.3.1

package/src/prompts/skillList.js

@@ -0,0 +1,126 @@
+/**
+ * ============================================================
+ *  src/prompts/skillList.ts —— Skill 列表生成（积极使用版）
+ * ------------------------------------------------------------
+ *  设计原则（v3 重构）：
+ *    1. System Prompt 里只注入 frontmatter 元数据轻量列表
+ *       → 让 T 阶段的 LLM 知道"有哪些技能可用 + 何时触发 + 是什么类型"
+ *       → 不加载完整 SKILL.md（省 token，按需加载）
+ *    2. LLM 决定使用某个 skill 时，用 Read 工具读取对应 SKILL.md
+ *       → 类似 lazy loading：知道存在 → 需要时才加载详情
+ *    3. 格式对齐 Tools 的风格：每个 skill 固定 3 行信息
+ *    4. 完全依赖 frontmatter 声明（name / description / type / triggers），
+ *       不再做任何启发式推断。新增 skill 时必须在 frontmatter 显式声明
+ *       type 和 triggers 字段（缺省时给出占位提示）。
+ * ============================================================
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getResourceSearchPaths } from '../utils/resourcePaths.js';
+function stripQuotes(s) {
+    const trimmed = s.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function parseFrontmatter(content, sourceDir) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return null;
+    const frontmatter = match[1];
+    const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+    const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+    const typeMatch = frontmatter.match(/^type:\s*(.+)$/m);
+    const triggersMatch = frontmatter.match(/^triggers:\s*(.+)$/m);
+    if (!nameMatch || !descMatch)
+        return null;
+    return {
+        name: stripQuotes(nameMatch[1]),
+        description: stripQuotes(descMatch[1]),
+        type: typeMatch ? stripQuotes(typeMatch[1]) : undefined,
+        triggers: triggersMatch ? stripQuotes(triggersMatch[1]) : undefined,
+        sourceDir,
+    };
+}
+export async function getSkillList() {
+    const skills = [];
+    const seenNames = new Set();
+    // 双源扫描：cwd 优先 + packageRoot fallback；按数组顺序处理，已注册 name 跳过
+    const searchPaths = getResourceSearchPaths('skills', import.meta.url);
+    for (const root of searchPaths) {
+        try {
+            const entries = await readdir(root, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const sourceDir = join(root, entry.name);
+                const skillPath = join(sourceDir, 'SKILL.md');
+                try {
+                    const content = await readFile(skillPath, 'utf8');
+                    const meta = parseFrontmatter(content, sourceDir);
+                    if (meta && !seenNames.has(meta.name)) {
+                        seenNames.add(meta.name);
+                        skills.push(meta);
+                    }
+                }
+                catch {
+                }
+            }
+        }
+        catch {
+        }
+    }
+    return skills;
+}
+/**
+ * 生成积极的 skill 列表提示词。
+ *
+ * 输出格式（每个 skill 固定 3 行）:
+ *   ## /skill-name —— 一句话标题
+ *   - **触发时机**: 用户说 "xxx"、"yyy" 时使用
+ *   - **功能**: 一句话描述这个 skill 做什么
+ *   - **类型**: prompt / local / local-jsx
+ *
+ * 关键设计决策：
+ *   - 不加载 SKILL.md 全文（节省 ~1500+ tokens/skill）
+ *   - 只输出 name + description（每个 skill ~40 tokens）
+ *   - 明确告诉 LLM "决定用时再 Read SKILL.md"
+ */
+export function formatSkillHint(skills) {
+    if (skills.length === 0) {
+        return '';
+    }
+    const lines = [];
+    // ---- 标题段 ----
+    lines.push('# 可用技能（/命令）');
+    lines.push('');
+    lines.push('以下是当前可用的技能（**双源**：用户项目目录 + minimal-agent 包目录，同名时项目优先）。**当用户意图匹配某个技能的触发时机时，你应该主动使用它**。');
+    lines.push('在使用前，先用 Read 工具读取下方每个技能卡片里的 `**技能目录**` 路径 + `/SKILL.md` 了解完整流程。');
+    lines.push('');
+    // ---- 每个技能的卡片 ----
+    for (const skill of skills) {
+        const type = skill.type ?? 'prompt（展开为系统提示词，指导模型执行复杂任务）';
+        const triggers = skill.triggers ?? '（详见 SKILL.md）';
+        lines.push(`## ${skill.name}`);
+        lines.push(`- **触发时机**: ${triggers}`);
+        lines.push(`- **功能**: ${skill.description}`);
+        lines.push(`- **类型**: ${type}`);
+        lines.push(`- **技能目录**: \`${skill.sourceDir}\``);
+        lines.push('');
+    }
+    // ---- 使用流程指引 ----
+    lines.push('## 技能调用流程');
+    lines.push('');
+    lines.push('```');
+    lines.push('1. 在 T 阶段判断用户意图是否匹配某个技能的触发时机');
+    lines.push('2. 匹配 → 在 A 阶段用 Read 工具读取该技能卡片的"技能目录"/SKILL.md');
+    lines.push('3. 按照 SKILL.md 的 Quick Reference 和流程执行');
+    lines.push('4. 技能脚本（scripts/）与 SKILL.md 位于同一目录下，用绝对路径执行');
+    lines.push('5. 如果技能类型是 prompt，将其内容作为额外上下文指导后续操作');
+    lines.push('```');
+    lines.push('');
+    lines.push('> 💡 技能是工具的组合拳。单个工具是基础操作；技能是针对特定场景的标准化工作流。');
+    return lines.join('\n');
+}

package/src/prompts/system.js

@@ -0,0 +1,155 @@
+/**
+ * ============================================================
+ *  src/prompts/system.ts —— 系统提示词
+ * ------------------------------------------------------------
+ *  系统提示词（system message）是放在历史最前面的固定指令，告诉模型：
+ *    - 自己的身份
+ *    - 当前工作环境（cwd / OS / 时间）
+ *    - 可用的工具及使用建议
+ *    - 可用技能及调用时机
+ *    - 输出风格偏好
+ *
+ *  与 kakadeai 的 systemPromptSection() 复杂的分段缓存不同，
+ *  最小化版只输出一段纯文本，简单直接。
+ * ============================================================
+ */
+import { homedir } from 'node:os';
+import { loadProjectInstructions } from './projectInstructions.js';
+import { getSkillList, formatSkillHint } from './skillList.js';
+/**
+ * 生成系统提示词。
+ *
+ * @param cwd    当前工作目录
+ * @param tools  可用工具数组（用于在 prompt 里列出工具名）
+ */
+export async function getSystemPrompt(cwd, tools) {
+    const toolList = tools.map((t) => `  - ${t.name}`).join('\n');
+    const today = new Date().toISOString().slice(0, 10);
+    // 实时扫描 skills 目录（无缓存）—— 每次重建 system prompt 时都读最新的 SKILL.md，
+    // 保证用户中途复制新 skill 进去也能立刻识别
+    const skills = await getSkillList();
+    const skillHint = formatSkillHint(skills);
+    return `你是 minimal-agent，一个最小化的 AI 编程助手。
+你运行在用户的本地终端里，可以读取、修改、创建文件，可以搜索文件名和文件内容，可以联网搜索最新信息。
+
+# 工作环境
+- 当前工作目录: ${cwd}
+- 用户主目录: ${homedir()}
+- 平台: ${process.platform}
+- 当前日期: ${today}
+
+# 时间感知规则（重要！搜索前必读）
+- **每次执行 WebSearch 前，必须先确认当前日期**
+- 当前日期：${today}
+- 搜索时必须在 query 末尾附带日期限制，如 "... as of [日期]" 或 "... ${today}"
+- 例如搜索日本政策时写："日本入境政策 ${today}"
+- 禁止使用 "现在"、"最近"、"最新" 等模糊时间词——必须用具体日期
+
+# 可用工具
+${toolList}
+
+# 工具使用规范
+- 修改既有文件之前，必须用 Read 工具读取相关代码的最新内容。
+  "我记得"、"我之前看过"、"应该差不多"都不算读过——必须在本轮任务中实际调用 Read。
+  尤其当你要参考某个文件的写法来实现类似功能时，必须先重读该文件的关键部分（函数实现、判断逻辑、数据流），理解清楚后再动手。
+- Edit 工具的 old_string 必须在文件中唯一；不唯一时请扩大上下文或显式 replace_all=true。
+- 同一文件需要修改多处（3 处及以上）时优先用 MultiEdit：所有 edit 按顺序在内存中应用，**全部成功才落盘**；任一失败磁盘不动，避免中间状态污染。单点修改继续用 Edit。
+- Write 覆盖既有文件前同样必须先 Read（与 Edit 对称，未先 Read 会被拒绝并提示"请先 Read"）；写新文件无此要求。
+- 创建新文件用 Write，或 Edit 时 old_string 传空字符串。
+- 找文件用 Glob（"**/*.ts"），找文件内容用 Grep（基于 ripgrep）。
+- 当用户问到训练截止后才出现的信息（最新版本号、近期新闻、第三方 API 文档）时用 WebSearch；优先精确的自然语言查询。
+- 当需要执行终端命令（安装依赖、运行测试/构建/lint、git 操作、文件系统操作等）时用 Bash。
+  ⚠️ **Bash 是万能工具，但必须作为最后手段**：当 Read/Edit/Write/Glob/Grep 等专用工具无法完成任务时，才考虑用 Bash。
+  不要用 Bash 执行 find/grep/cat/head/tail/sed/awk/echo 等命令来替代专用工具——专用工具提供更好的用户体验和可审计性。
+  Bash 有安全黑名单（rm -rf /、mkfs、shutdown 等危险命令会被拦截），但仍需谨慎：
+  先确认命令无害再执行，避免不可逆操作（如 git push --force、git reset --hard）。
+  长时间运行的命令（npm install、bun test）注意超时设置；需要交互输入的命令不要用 Bash（用 Write 写脚本代替）。
+  Bash 已识别"信息性退出码"：grep/rg/find/diff/test 的 exit=1（无匹配 / 部分不可访问 / 有差异 / 条件假）会自动判为成功，不要因 1 而重试。
+  破坏性命令（git reset --hard / git push -f / rm -rf 等）会被 Bash 主动在输出头部加 ⚠️ 警告（不拦截），看到时应向用户确认意图。
+- 当需要获取网页静态文本内容（抓取文档、读取文章）时用 WebFetch。
+  WebBrowser 依赖可选包（playwright-core + chromium）—— **默认假定未安装**，
+  仅在 WebFetch 明确无法满足（如需要 JS 渲染后的内容、点击按钮、填表单、截图）时再尝试。
+  如果 WebBrowser 报"无法启动浏览器/缺少依赖"，不要重试，改回 WebFetch 或告知用户安装依赖。
+- 一次回答里可以并行调用多个只读工具（Read/Glob/Grep/WebSearch/WebFetch），写工具（Edit/Write/Bash）请逐个执行。
+
+# 技能系统（积极使用）
+${skillHint}
+
+# 插件系统（被动触发）
+- minimal-agent 在 \`plugins/\` 目录下加载用户安装的插件，每个插件可暴露形如 \`/<cmd>\` 的命令。
+  与 skill 不同，**插件命令必须由用户主动输入才触发**——你**不要**主动调用或模拟这些命令，
+  也不要在工具调用里假装在跑插件。
+- 当某个插件命令在执行中（你会在当轮用户消息里看到该插件注入的上下文 / 阶段标记 / 哨兵约定），
+  请严格按照该插件给出的指引行动，不要绕开它的契约。
+- 在**常规对话**（无插件注入的阶段标记 / 哨兵约定）中，不要凭空使用这些标记或哨兵词。
+
+# 文件读取规范（重要！防止上下文污染）
+## 读取策略（按场景选择）
+### 场景 1：不确定文件内容
+→ 先 Grep("关键字", path="文件路径") 定位
+→ 再 Read(file_path, offset=X, limit=Y) 读指定区域
+
+### 场景 2：知道要改哪个函数
+→ 直接 Read(file_path, offset=1, limit=400) 先读前 400 行
+→ 或者用 Grep 找到行号后 Read(file_path, offset=行号, limit=200)
+
+### 场景 3：大文件（>256KB）
+→ 不要一次性读，用 Grep 定位关键部分
+→ 分多次小范围 Read，每次不超过 200 行
+→ 例如：Read(file, offset=1, limit=100) → Read(file, offset=101, limit=100)
+
+### 场景 4：需要看 imports/exports
+→ Read(file, offset=1, limit=50) 只读文件头部
+
+## 警惕信号
+- 遇到 "文件过大" 错误 → 说明你读了不该读的大文件，改用分段读
+- 遇到 "输出超过 30000 字符" → 说明单次读太多，改小 limit
+
+# 输出风格
+- 用中文回答用户。
+- 简明扼要，避免重复解释代码做了什么 —— 让代码自身说话。
+- 报错时给出根因，不要只复述错误消息。
+- 不主动跑测试或 typecheck，除非用户要求。
+
+# 行为约束
+- 没有用户许可不要执行破坏性操作（rm -rf / git reset --hard / git push --force 等）。
+- 如果用户的请求不清晰，先用一句话澄清再动手。
+- 任务完成后用一两句话总结改了什么，不要长篇大论。
+
+# 中断支持
+- 用户可以随时按 ESC 或 Ctrl+C 中断你的工作。
+- 中断后等待用户输入新任务，不要自行继续执行被中断的操作。
+- 如果用户输入了新任务，直接响应新任务，不必提及之前被中断的操作。
+
+# 任务识别
+- 用户开始新任务时（"帮我做 X"、"这次做 YYY"），不要继续之前未完成的旧任务
+- 用户说"继续"、"接着做"、"再加一个"时，保持当前任务上下文
+- 用户说"重新开始"、"不算了，做 X"时，立即放下旧任务
+- 意图模糊时，先用一句话澄清："你是继续刚才的，还是开始新的？"`;
+}
+/**
+ * 生成完整系统提示词：getSystemPrompt + 项目级 minimal-agent.md 指令。
+ *
+ * 合并到**单条** system message，避免某些 provider（如 MiniMax）多 system
+ * message 时返回 400 "invalid chat setting"。启动时（main.tsx buildInitialHistory）
+ * 和 /new（useChat.clearHistory）都用这个 helper，确保两处行为一致。
+ */
+export async function buildFullSystemPrompt(cwd, tools) {
+    let content = await getSystemPrompt(cwd, tools);
+    const projectInstructions = await loadProjectInstructions(cwd);
+    if (projectInstructions) {
+        content += [
+            '',
+            '--- 项目指令（minimal-agent.md） ---',
+            '',
+            '⚠️ 时效性声明：',
+            '- 以下内容来源于项目根目录的 `minimal-agent.md` 文件，具有时效性，可能已过时。',
+            '- 它是参考线索，不是绝对真理。当它与实际代码或文件内容冲突时，以代码为准。',
+            '- 涉及代码和项目文件的任何操作前，必须先用 Read / Grep 工具确认当前代码的实际状态，再基于最新信息做决策，不要仅凭此文档的描述操作。',
+            '- 如果你发现 `minimal-agent.md` 的描述与当前代码不一致，应主动用 Write 工具更新 `minimal-agent.md` 使其与代码保持同步。',
+            '',
+            projectInstructions,
+        ].join('\n');
+    }
+    return content;
+}

package/src/session/runTurn.js

@@ -0,0 +1,41 @@
+/**
+ * ============================================================
+ *  src/session/runTurn.ts —— Headless 单 turn 执行器
+ * ------------------------------------------------------------
+ *  把"读 session 文件 → 跑 runQuery → 写 session 文件"封装成单一入口。
+ *  PR 4 HTTP server 的每个请求 handler 用它即可，无需自己拼装。
+ *
+ *  调用方契约：
+ *    - sessionFile: per-chat 隔离的上下文文件路径（参见 sessionPath.sessionFileFor）
+ *    - systemPrompt: 当 loadContext 返回 null（首次会话）时用它建初始 history；
+ *      未提供则用空数组开局（少数 case 才合理，例如不需要 system prompt）
+ *    - sessionState: 多并发场景必须 per-request 创建一份，避免不同 chat 串扰
+ *    - signal:      调用方持有 AbortController，断开/超时时主动 abort
+ *
+ *  落盘策略：
+ *    用 try/finally 包住 runQuery；不管成功、抛错、还是被中断都保存当前
+ *    history。中断时 loop.ts 内部会先把"用户按下了 ESC/Ctrl+C"标记
+ *    消息追加到 history，所以落盘的也是合法且完整的会话状态。
+ * ============================================================
+ */
+import { loadContext, saveContext } from '../context/persistContext.js';
+import { runWithPlugins } from '../plugins/pluginRunner.js';
+export async function* runTurn(opts) {
+    const loaded = await loadContext(opts.sessionFile);
+    const history = loaded ??
+        (opts.systemPrompt
+            ? [{ role: 'system', content: opts.systemPrompt }]
+            : []);
+    try {
+        yield* runWithPlugins(opts.userInput, {
+            provider: opts.provider,
+            history,
+            signal: opts.signal,
+            maxTurns: opts.maxTurns,
+            sessionState: opts.sessionState,
+        });
+    }
+    finally {
+        await saveContext(history, opts.sessionFile);
+    }
+}

package/src/session/sessionState.js

@@ -0,0 +1,19 @@
+/**
+ * ============================================================
+ *  src/session/sessionState.ts —— 会话级隔离状态
+ * ------------------------------------------------------------
+ *  把 reactiveCompact + microCompactLite 的可注入状态打包。
+ *
+ *  TUI / print 不需要它（不传 → 默认走模块单例，行为不变）；
+ *  HTTP server per-request 调 createSessionState() 拿独立一份，
+ *  让每个 chatId 的工具结果去重缓存、反应式自救标记互不串扰。
+ * ============================================================
+ */
+import { createMicroCompactState, } from '../context/microCompactLite.js';
+import { createReactiveCompactState, } from '../context/reactiveCompact.js';
+export function createSessionState() {
+    return {
+        reactive: createReactiveCompactState(),
+        microCompact: createMicroCompactState(),
+    };
+}