dominds 1.4.2 → 1.5.2

package/dist/tools/prompts/memory/zh/scenarios.md

@@ -0,0 +1,174 @@
+# memory 使用场景
+
+## 模板（场景）
+
+### 场景格式
+
+- 目标
+- 前置条件
+- 步骤
+- 期望信号
+- 失败分支处理
+- 完成判据
+
+## 场景 1：任务进度跟踪
+
+### 场景描述
+
+在长时间任务中，需要持久化任务进度，以便重启后继续。
+
+### 示例
+
+**添加任务列表**
+
+```typescript
+add_memory({
+  path: 'project/i18n-tasks',
+  content:
+    '## 待办任务\n\n- [ ] 创建 ws_mod 手册\n- [ ] 创建 team_mgmt 手册\n- [ ] 创建 memory 手册\n- [ ] 创建 control 手册\n\n## 进行中\n- [ ] 创建 ws_mod 手册 [100%]',
+});
+```
+
+**更新任务进度**
+
+```typescript
+replace_memory({
+  path: 'project/i18n-tasks',
+  content:
+    '## 待办任务\n\n- [ ] 创建 team_mgmt 手册\n- [ ] 创建 memory 手册\n- [ ] 创建 control 手册\n\n## 已完成\n- [x] 创建 ws_mod 手册\n\n## 进行中\n- [ ] 创建 team_mgmt 手册 [50%]',
+});
+```
+
+## 场景 2：用户偏好存储
+
+### 场景描述
+
+保存用户偏好设置，例如编程语言、主题等。
+
+### 示例
+
+**保存用户偏好**
+
+```typescript
+add_memory({
+  path: 'user/preferences',
+  content:
+    '## 用户偏好\n\n- 编程语言: TypeScript\n- 代码风格: strict\n- 主题: dark\n- 自动保存: true',
+});
+```
+
+**更新偏好**
+
+```typescript
+replace_memory({
+  path: 'user/preferences',
+  content:
+    '## 用户偏好\n\n- 编程语言: TypeScript\n- 代码风格: strict\n- 主题: light\n- 自动保存: true',
+});
+```
+
+## 场景 3：上下文信息保存
+
+### 场景描述
+
+在复杂任务中，保存重要的上下文信息，避免重复查询。
+
+### 示例
+
+**保存 API 信息**
+
+```typescript
+add_memory({
+  path: 'context/api-endpoints',
+  content:
+    '## API 端点\n\n- 用户登录: POST /api/auth/login\n- 获取用户信息: GET /api/user/info\n- 更新用户设置: PUT /api/user/settings\n\n## 认证\n- 使用 Bearer Token\n- 有效期: 24 小时',
+});
+```
+
+**保存技术栈**
+
+```typescript
+add_memory({
+  path: 'context/tech-stack',
+  content:
+    '## 技术栈\n\n- 前端: React + TypeScript\n- 后端: Node.js + Express\n- 数据库: PostgreSQL\n- 缓存: Redis',
+});
+```
+
+## 场景 4：会议记录
+
+### 场景描述
+
+保存会议要点和决策。
+
+### 示例
+
+```typescript
+add_memory({
+  path: 'meeting/2024-01-15',
+  content:
+    '## 会议纪要: 2024-01-15\n\n### 参与者\n- @fullstack\n- @i18n\n- @ux\n\n### 议题\n1. i18n 手册创建计划\n2. man 函数 UX 改进\n\n### 决策\n- 优先创建 ws_mod 和 team_mgmt 手册\n- man 函数支持模糊匹配\n\n### 待办\n- @i18n: 创建 memory 手册\n- @fullstack: 优化 man 函数',
+});
+```
+
+## 场景 5：知识库
+
+### 场景描述
+
+建立个人知识库，保存学习笔记。
+
+### 示例
+
+```typescript
+add_memory({
+  path: 'knowledge/typescript-tips',
+  content:
+    '## TypeScript 技巧\n\n### 1. 类型推断\nconst x = 1; // 类型推断为 number\n\n### 2. 接口 vs 类型\n- 接口: 可扩展，适合对象类型\n- 类型: 支持联合类型、交叉类型\n\n### 3. strict 模式\n启用 strict 模式可以获得更好的类型安全',
+});
+```
+
+## 场景 6：临时笔记
+
+### 场景描述
+
+临时保存需要稍后处理的信息。
+
+### 示例
+
+```typescript
+add_memory({
+  path: 'scratchpad/temp-notes',
+  content:
+    '## 临时笔记\n\n- TODO: 检查 team.yaml 配置\n- TODO: 验证 man 函数类型\n- TODO: 更新差遣牒进度',
+});
+```
+
+**处理完后删除**
+
+```typescript
+drop_memory({
+  path: 'scratchpad/temp-notes',
+});
+```
+
+## 场景 7：清理过时记忆
+
+### 场景描述
+
+定期清理不再需要的记忆。
+
+### 示例
+
+```typescript
+// 查看当前所有记忆（智能体可读取）
+// 逐个删除不需要的记忆
+drop_memory({
+  path: 'project/old-feature',
+});
+```
+
+或者使用 `clear_memory` 清空所有记忆（谨慎使用）：
+
+```typescript
+clear_memory({});
+```

package/dist/tools/prompts/memory/zh/tools.md

@@ -0,0 +1,154 @@
+# memory 工具参考
+
+## 模板（工具）
+
+### 阅读方式
+
+- "工具契约（Schema）" 为参数/返回的权威来源。
+
+### 单工具字段顺序
+
+1. 用途
+2. 调用签名
+3. 参数（参见 schema）
+4. 前置条件
+5. 成功信号
+6. 失败/错误
+7. 可直接执行示例
+8. 常见误用
+
+## 工具列表
+
+### 1. add_memory
+
+创建新记忆（路径不存在时）。
+
+**参数：**
+
+- `path`（必需）：记忆的唯一标识符
+- `content`（必需）：记忆内容
+
+**返回：**
+
+```yaml
+status: ok|error
+path: <记忆路径>
+content_size: <内容字节数>
+created_at: <创建时间戳>
+```
+
+**错误：**
+
+- `MEMORY_ALREADY_EXISTS`：路径已存在，使用 `replace_memory` 更新
+
+### 2. replace_memory
+
+更新已有记忆（路径存在时）。
+
+**参数：**
+
+- `path`（必需）：记忆的唯一标识符
+- `content`（必需）：新的记忆内容
+
+**返回：**
+
+```yaml
+status: ok|error
+path: <记忆路径>
+content_size: <内容字节数>
+updated_at: <更新时间戳>
+```
+
+**错误：**
+
+- `MEMORY_NOT_FOUND`：路径不存在，使用 `add_memory` 创建
+
+### 3. drop_memory
+
+删除指定记忆。
+
+**参数：**
+
+- `path`（必需）：要删除的记忆路径
+
+**返回：**
+
+```yaml
+status: ok|error
+path: <记忆路径>
+deleted_at: <删除时间戳>
+```
+
+**错误：**
+
+- `MEMORY_NOT_FOUND`：路径不存在
+
+### 4. clear_memory
+
+清空所有个人记忆。
+
+**警告：** 此操作不可恢复！
+
+**参数：** 无
+
+**返回：**
+
+```yaml
+status: ok|error
+cleared_count: <删除的记忆数量>
+cleared_at: <删除时间戳>
+```
+
+**错误：**
+
+- 无（即使没有记忆也会返回成功）
+
+## 使用示例
+
+### 添加新记忆
+
+```typescript
+add_memory({
+  path: 'project/todo',
+  content: '- 完成 i18n 文档\n- 编写测试用例\n- 更新 README',
+});
+```
+
+### 更新已有记忆
+
+```typescript
+replace_memory({
+  path: 'project/todo',
+  content: '- 完成 i18n 文档 [DONE]\n- 编写测试用例 [IN PROGRESS]\n- 更新 README',
+});
+```
+
+### 删除记忆
+
+```typescript
+drop_memory({
+  path: 'project/todo',
+});
+```
+
+### 清空所有记忆
+
+```typescript
+clear_memory({});
+```
+
+## YAML 输出契约
+
+所有工具的输出都使用 YAML 格式，便于程序化处理：
+
+- `status`：操作状态，`ok` 表示成功，`error` 表示失败
+- `path`：记忆路径
+- 其他字段：具体操作的附加信息
+
+错误时返回：
+
+```yaml
+status: error
+error_code: <错误代码>
+message: <错误消息>
+```

package/dist/tools/ripgrep.js

@@ -23,6 +23,11 @@ function yamlFlowStringArray(values) {
         return '[]';
     return `[${values.map(yamlQuote).join(', ')}]`;
 }
+function yamlFlowNumberArray(values) {
+    if (values.length === 0)
+        return '[]';
+    return `[${values.join(', ')}]`;
+}
 function requireNonEmptyStringArg(args, key) {
     const value = args[key];
     if (typeof value !== 'string' || value.trim() === '') {
@@ -223,6 +228,176 @@ function formatForbiddenSearchPathAccessDeniedYaml(mode, pattern, searchPath, fo
     ].join('\n');
     return formatYamlCodeBlock(yaml);
 }
+const RIPGREP_SNIPPET_TEXT_CHAR_LIMIT = 400;
+const RIPGREP_SNIPPET_OUTPUT_CHAR_LIMIT = 200000;
+const RIPGREP_SNIPPET_RESULTS_CHAR_BUDGET = RIPGREP_SNIPPET_OUTPUT_CHAR_LIMIT - 2048;
+function truncateRipgrepSnippetText(text, maxChars = RIPGREP_SNIPPET_TEXT_CHAR_LIMIT) {
+    if (text.length <= maxChars)
+        return { text, truncated: false, originalChars: text.length };
+    const suffix = `...[truncated ${text.length - maxChars} chars]`;
+    if (suffix.length >= maxChars) {
+        return { text: suffix.slice(0, maxChars), truncated: true, originalChars: text.length };
+    }
+    const keepChars = maxChars - suffix.length;
+    return {
+        text: `${text.slice(0, keepChars)}${suffix}`,
+        truncated: true,
+        originalChars: text.length,
+    };
+}
+function sumNumbers(values) {
+    let total = 0;
+    for (const value of values)
+        total += value;
+    return total;
+}
+function renderRipgrepSnippetResult(result) {
+    const match = truncateRipgrepSnippetText(result.match);
+    const renderedBefore = (result.before ?? []).map((line) => truncateRipgrepSnippetText(line));
+    const renderedAfter = (result.after ?? []).map((line) => truncateRipgrepSnippetText(line));
+    const beforeOriginalChars = renderedBefore.map((line) => line.originalChars);
+    const afterOriginalChars = renderedAfter.map((line) => line.originalChars);
+    const textTruncated = match.truncated ||
+        renderedBefore.some((line) => line.truncated) ||
+        renderedAfter.some((line) => line.truncated);
+    const reasons = textTruncated ? ['per_text_char_limit'] : [];
+    const originalTextChars = match.originalChars + sumNumbers(beforeOriginalChars) + sumNumbers(afterOriginalChars);
+    return {
+        yaml: [
+            `  - path: ${yamlQuote(result.path)}`,
+            `    line: ${result.line}`,
+            `    col: ${result.col}`,
+            `    text_truncated: ${textTruncated}`,
+            `    match: ${yamlQuote(match.text)}`,
+            ...(result.before
+                ? [`    before: ${yamlFlowStringArray(renderedBefore.map((line) => line.text))}`]
+                : []),
+            ...(result.after
+                ? [`    after: ${yamlFlowStringArray(renderedAfter.map((line) => line.text))}`]
+                : []),
+            `    truncation:`,
+            `      applied: ${textTruncated}`,
+            `      reasons: ${yamlFlowStringArray(reasons)}`,
+            `      match_original_chars: ${match.originalChars}`,
+            `      before_original_chars: ${yamlFlowNumberArray(beforeOriginalChars)}`,
+            `      after_original_chars: ${yamlFlowNumberArray(afterOriginalChars)}`,
+        ].join('\n'),
+        textTruncated,
+        originalTextChars,
+    };
+}
+function fitRipgrepSnippetResults(results) {
+    const rendered = [];
+    let usedChars = 0;
+    let textTruncated = false;
+    let outputCharsTruncated = false;
+    let textTrimmedResultCount = 0;
+    let shownOriginalTextChars = 0;
+    let omittedOriginalTextChars = 0;
+    let omittedResultsByOutputBudget = 0;
+    for (let idx = 0; idx < results.length; idx += 1) {
+        const result = results[idx];
+        const next = renderRipgrepSnippetResult(result);
+        textTruncated = textTruncated || next.textTruncated;
+        if (next.textTruncated)
+            textTrimmedResultCount += 1;
+        const nextChars = next.yaml.length + (rendered.length > 0 ? 1 : 0);
+        if (usedChars + nextChars > RIPGREP_SNIPPET_RESULTS_CHAR_BUDGET) {
+            outputCharsTruncated = true;
+            omittedResultsByOutputBudget = results.length - idx;
+            omittedOriginalTextChars += next.originalTextChars;
+            for (let rest = idx + 1; rest < results.length; rest += 1) {
+                omittedOriginalTextChars += renderRipgrepSnippetResult(results[rest]).originalTextChars;
+            }
+            break;
+        }
+        rendered.push(next.yaml);
+        usedChars += nextChars;
+        shownOriginalTextChars += next.originalTextChars;
+    }
+    if (rendered.length < results.length && !outputCharsTruncated) {
+        outputCharsTruncated = true;
+        omittedResultsByOutputBudget = results.length - rendered.length;
+    }
+    return {
+        rendered,
+        textTruncated,
+        outputCharsTruncated,
+        textTrimmedResultCount,
+        shownOriginalTextChars,
+        omittedOriginalTextChars,
+        omittedResultsByOutputBudget,
+    };
+}
+function buildRipgrepSnippetSummary(input) {
+    if (input.totalMatches === 0)
+        return 'No matches.';
+    if (input.truncatedByMatchLimit && input.truncatedByOutputChars) {
+        return `Found ${input.totalMatches} matches; showing ${input.shownResults} snippets within max_results/output limits (truncated=true).`;
+    }
+    if (input.truncatedByOutputChars) {
+        return `Found ${input.totalMatches} matches; showing ${input.shownResults} snippets within output size limit (truncated=true).`;
+    }
+    if (input.truncatedByMatchLimit) {
+        return `Showing first ${input.maxResults} of ${input.totalMatches} matches (truncated=true).`;
+    }
+    if (input.textTruncated) {
+        return `Found ${input.totalMatches} matches; long snippet lines were trimmed for readability.`;
+    }
+    return `Found ${input.totalMatches} matches.`;
+}
+function formatRipgrepSnippetYaml(input) {
+    const fitted = fitRipgrepSnippetResults(input.results);
+    const truncatedByMatchLimit = input.totalMatches > input.maxResults;
+    const truncated = truncatedByMatchLimit || fitted.outputCharsTruncated || fitted.textTruncated;
+    const truncationReasons = [];
+    if (truncatedByMatchLimit)
+        truncationReasons.push('max_results');
+    if (fitted.outputCharsTruncated)
+        truncationReasons.push('output_char_budget');
+    if (fitted.textTruncated)
+        truncationReasons.push('per_text_char_limit');
+    const summary = buildRipgrepSnippetSummary({
+        totalMatches: input.totalMatches,
+        shownResults: fitted.rendered.length,
+        maxResults: input.maxResults,
+        truncatedByMatchLimit,
+        truncatedByOutputChars: fitted.outputCharsTruncated,
+        textTruncated: fitted.textTruncated,
+    });
+    const yaml = [
+        `status: ok`,
+        `pattern: ${yamlQuote(input.pattern)}`,
+        `mode: snippets`,
+        `path: ${yamlQuote(input.searchPath)}`,
+        ...(input.globs.length > 0 ? [`globs: ${yamlFlowStringArray(input.globs)}`] : []),
+        `case: ${input.caseMode}`,
+        `fixed_strings: ${input.fixedStrings}`,
+        `regex: ${!input.fixedStrings}`,
+        `truncated: ${truncated}`,
+        `truncated_by_output_chars: ${fitted.outputCharsTruncated}`,
+        `snippet_text_truncated: ${fitted.textTruncated}`,
+        `limits:`,
+        `  max_results: ${input.maxResults}`,
+        `  max_output_chars: ${RIPGREP_SNIPPET_OUTPUT_CHAR_LIMIT}`,
+        `  per_text_char_limit: ${RIPGREP_SNIPPET_TEXT_CHAR_LIMIT}`,
+        `totals:`,
+        `  files_matched: ${input.fileCount}`,
+        `  matches: ${input.totalMatches}`,
+        `  shown_results: ${fitted.rendered.length}`,
+        `truncation:`,
+        `  applied: ${truncated}`,
+        `  reasons: ${yamlFlowStringArray(truncationReasons)}`,
+        `  text_trimmed_result_count: ${fitted.textTrimmedResultCount}`,
+        `  omitted_results_by_output_budget: ${fitted.omittedResultsByOutputBudget}`,
+        `  shown_original_text_chars: ${fitted.shownOriginalTextChars}`,
+        `  omitted_original_text_chars: ${fitted.omittedOriginalTextChars}`,
+        `summary: ${yamlQuote(summary)}`,
+        `results:`,
+        ...fitted.rendered,
+    ].join('\n');
+    return formatYamlCodeBlock(yaml);
+}
 function defaultBaseOptions() {
     return {
         globs: [],
@@ -549,39 +724,17 @@ async function runRipgrepSnippets(caller, pattern, searchPath, options) {
             const after = lines.slice(idx0 + 1, idx0 + 1 + options.contextAfter);
             results.push({ path: filePath, line: ln, col, match: text, before, after });
         }
-        const truncated = totalMatches > options.maxResults;
-        const summary = totalMatches === 0
-            ? 'No matches.'
-            : truncated
-                ? `Showing first ${options.maxResults} of ${totalMatches} matches (truncated=true).`
-                : `Found ${totalMatches} matches.`;
-        const yaml = [
-            `status: ok`,
-            `pattern: ${yamlQuote(pattern)}`,
-            `mode: snippets`,
-            `path: ${yamlQuote(searchPath)}`,
-            ...(options.globs.length > 0 ? [`globs: ${yamlFlowStringArray(options.globs)}`] : []),
-            `case: ${options.caseMode}`,
-            `fixed_strings: ${options.fixedStrings}`,
-            `regex: ${!options.fixedStrings}`,
-            `truncated: ${truncated}`,
-            `limits:`,
-            `  max_results: ${options.maxResults}`,
-            `totals:`,
-            `  files_matched: ${fileSet.size}`,
-            `  matches: ${totalMatches}`,
-            `summary: ${yamlQuote(summary)}`,
-            `results:`,
-            ...results.map((r) => [
-                `  - path: ${yamlQuote(r.path)}`,
-                `    line: ${r.line}`,
-                `    col: ${r.col}`,
-                `    match: ${yamlQuote(r.match)}`,
-                `    before: ${yamlFlowStringArray(r.before)}`,
-                `    after: ${yamlFlowStringArray(r.after)}`,
-            ].join('\n')),
-        ].join('\n');
-        return formatYamlCodeBlock(yaml);
+        return formatRipgrepSnippetYaml({
+            pattern,
+            searchPath,
+            globs: options.globs,
+            caseMode: options.caseMode,
+            fixedStrings: options.fixedStrings,
+            maxResults: options.maxResults,
+            fileCount: fileSet.size,
+            totalMatches,
+            results,
+        });
     }
     catch (error) {
         return formatYamlCodeBlock([
@@ -771,36 +924,17 @@ async function runRipgrepSearch(caller, pattern, searchPath, rawRgArgs) {
             if (results.length < options.maxResults)
                 results.push({ path: filePath, line: ln, col, match: text });
         }
-        const truncated = totalMatches > options.maxResults;
-        const summary = totalMatches === 0
-            ? 'No matches.'
-            : truncated
-                ? `Showing first ${options.maxResults} of ${totalMatches} matches (truncated=true).`
-                : `Found ${totalMatches} matches.`;
-        const yaml = [
-            `status: ok`,
-            `pattern: ${yamlQuote(pattern)}`,
-            `mode: snippets`,
-            `path: ${yamlQuote(searchPath)}`,
-            `case: smart`,
-            `fixed_strings: false`,
-            `regex: true`,
-            `truncated: ${truncated}`,
-            `limits:`,
-            `  max_results: ${options.maxResults}`,
-            `totals:`,
-            `  files_matched: ${fileSet.size}`,
-            `  matches: ${totalMatches}`,
-            `summary: ${yamlQuote(summary)}`,
-            `results:`,
-            ...results.map((r) => [
-                `  - path: ${yamlQuote(r.path)}`,
-                `    line: ${r.line}`,
-                `    col: ${r.col}`,
-                `    match: ${yamlQuote(r.match)}`,
-            ].join('\n')),
-        ].join('\n');
-        return formatYamlCodeBlock(yaml);
+        return formatRipgrepSnippetYaml({
+            pattern,
+            searchPath,
+            globs: [],
+            caseMode: 'smart',
+            fixedStrings: false,
+            maxResults: options.maxResults,
+            fileCount: fileSet.size,
+            totalMatches,
+            results,
+        });
     }
     catch (error) {
         return formatYamlCodeBlock([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dominds",
-  "version": "1.4.2",
+  "version": "1.5.2",
   "description": "DevOps Mindsets — Sustainable Agentic Product Lifecycle",
   "type": "commonjs",
   "private": false,
@@ -53,7 +53,7 @@
     "pnpm": ">=10.30.3"
   },
   "dependencies": {
-    "@longrun-ai/codex-auth": "^0.9.0",
+    "@longrun-ai/codex-auth": "^0.9.1",
     "@anthropic-ai/sdk": "^0.78.0",
     "openai": "^6.27.0",
     "@modelcontextprotocol/sdk": "^1.27.1",