dsh-soul-forging 0.1.6 → 0.1.8

package/README.md

@@ -79,6 +79,36 @@ cd dsh-soul-forging && bash install.sh
 
 两种都**不需要服务器**。想换记忆位置：设 `MEMORY_DIR`，或插件配置里改 `memoryDir`。
 
+### 装的时候可能遇到的两个坑
+
+**① 全局安装要 sudo**
+
+```bash
+sudo npm i -g dsh-soul-forging
+```
+
+不给 sudo 会报 `EACCES: permission denied, mkdir '/usr/local/lib/node_modules'`。
+不想用 sudo 就换用户级 prefix：`npm config set prefix ~/.npm-global`。
+
+**② 国内镜像源会滞后**
+
+如果配了淘宝/腾讯云之类的镜像，新版本可能要几小时才同步，装的时候报
+`No matching version found for xxx@0.y.z`。这时候指定官方源：
+
+```bash
+sudo npm i -g dsh-soul-forging --registry https://registry.npmjs.org
+```
+
+### 数据放在哪
+
+**代码和数据是分开的**：
+
+- 代码 → `node_modules/dsh-soul-forging/`（升级时会整个换掉）
+- 数据 → `~/.soul-forging/{memory,brain}`（你的记忆，升级不碰）
+
+这也是为什么不能用 `sudo` 跑 `soul` 系列命令——`sudo` 会把 `HOME` 变成 `/root`，
+它就会去找 `/root/.soul-forging`，看起来像"记忆丢了"。**日常用普通用户跑。**
+
 ---
 
 ## 用
@@ -117,6 +147,37 @@ soul-sync                         # 补摘要 → 瘦身 → 建索引 → 重
 
 ---
 
+## 三种人，三条路
+
+不是每个人都要一个"有性格的 AI"。所以装的时候可以选：
+
+```bash
+soul-init                  # 全套：记忆 + 性格模板（想长性格的人）
+soul-init --memory-only    # 只要记忆，不要性格
+soul-init --external       # 性格归你自己的 agent，我们只管记忆
+```
+
+| 模式 | 注入什么 | 适合谁 |
+|---|---|---|
+| `full` | SOUL + MEMORY + index + NOW | 想从零长出一个性格 |
+| `memory-only` | MEMORY + index + NOW | 只想让它记得住，不想动它的人设 |
+| `external` | index + NOW | 你的 agent 已经有自己的 prompt/人设了 |
+
+对应地，`soul-boot` 也能选：
+
+```bash
+soul-boot --mode memory-only
+soul-boot --with index.md,NOW.md      # 更细：自己挑文件
+```
+
+**空模板永远不会被注入。** 没填的 SOUL 里全是「（待填）」，塞进上下文比不塞更糟——
+模型会一本正经地介绍"我的名字是（待填）"。所以只要某页的占位符超过 3 处，就自动跳过。
+`--keep-empty` 可以强制保留（调试用）。
+
+铸魂清单也有 `status: skip`：用户明确说了不要性格，就别每次开局问他"你叫什么名字"。
+
+---
+
 ## 铸魂
 
 装完的第一件事不是干活，是**先把"我是谁"聊清楚**。

package/bin/init-home

@@ -1,11 +1,25 @@
 #!/usr/bin/env bash
 # 把空白记忆库铺到用户目录（装成插件时用这个）
+#
+#   soul-init                 全套：记忆 + 性格模板（想长性格的人）
+#   soul-init --memory-only   只要记忆，不要性格：不生成 SOUL.md，铸魂清单标 skip
+#   soul-init --external      性格归你自己的 agent：连 BOOTSTRAP 都不铺
+#
 # 默认 $HOME/.soul-forging/memory，可用 MEMORY_DIR 覆盖
 set -uo pipefail
 _SELF="$(readlink -f "${BASH_SOURCE[0]}" 2>/dev/null || echo "${BASH_SOURCE[0]}")"
 MEMKIT_ROOT="$(cd "$(dirname "$_SELF")/.." && pwd)"
 TARGET="${MEMORY_DIR:-$HOME/.soul-forging/memory}"
 
+MODE=full
+case "${1:-}" in
+  --memory-only) MODE=memory-only ;;
+  --external)    MODE=external ;;
+  "")            ;;
+  -h|--help)     sed -n '2,10p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+  *) echo "不认识的参数：$1"; exit 1 ;;
+esac
+
 if [ -d "$TARGET" ] && [ -n "$(ls -A "$TARGET" 2>/dev/null)" ]; then
   echo "目标已存在且有内容：$TARGET"
   echo "不覆盖。要重来先自己备份并删掉它。"
@@ -16,10 +30,61 @@ mkdir -p "$TARGET"
 cp -a "$MEMKIT_ROOT/memory/." "$TARGET/"
 # 数据目录也建出来（索引和服务写这里，别写进包目录）
 mkdir -p "${BRAIN_DIR:-$(dirname "$TARGET")/brain}"
-echo "✓ 空白记忆库已铺到：$TARGET"
+
+if [ "$MODE" != "full" ]; then
+  # 不要性格：SOUL 是个空模板，留着只会让模型看到"我的名字是（待填）"
+  rm -f "$TARGET/SOUL.md"
+  cat > "$TARGET/SOUL-NOTE.md" <<'NOTE'
+# 关于 SOUL.md
+
+这个记忆库是按"不要性格"装的：**没有 SOUL.md**，注入时也不会带性格那一块。
+
+- 想只要记忆、不要性格 → 保持现状，`soul-boot` 默认用 `memory-only` 模式
+- 以后想长性格了 → 把 `BOOTSTRAP.md` 的状态改回 `pending`，跑 `soul-init --force-soul` 或手写一份 `SOUL.md`
+- 记忆本身照常工作，跟性格无关
+NOTE
+fi
+
+if [ "$MODE" = "external" ]; then
+  rm -f "$TARGET/BOOTSTRAP.md"
+  echo "--external" > "$TARGET/.mode"
+else
+  echo "$MODE" > "$TARGET/.mode"
+fi
+
+# 把铸魂清单标成 skip（memory-only 时），别每次开局催用户
+if [ "$MODE" = "memory-only" ] && [ -f "$TARGET/BOOTSTRAP.md" ]; then
+  # 行尾可能有注释，所以匹配整行而不是 ^status: pending$
+  python3 - "$TARGET/BOOTSTRAP.md" <<'PY'
+import re, sys
+p = sys.argv[1]
+try:
+    s = open(p, encoding="utf-8").read()
+except OSError:
+    sys.exit(0)
+s = re.sub(r"^status:\s*\w+.*$", "status: skip", s, count=1, flags=re.M)
+open(p, "w", encoding="utf-8").write(s)
+PY
+fi
+
+echo "✓ 空白记忆库已铺到：$TARGET（模式：$MODE）"
 echo
-echo "接下来："
-echo "  1. 填 $TARGET/SOUL.md"
-echo "  2. 按 $TARGET/BOOTSTRAP.md 走一遍铸魂"
-echo "  3. 建索引：python3 $MEMKIT_ROOT/brain/index.py"
-echo "  4. 起服务：bash $MEMKIT_ROOT/bin/serve"
+case "$MODE" in
+  full)
+    echo "接下来："
+    echo "  1. 填 $TARGET/SOUL.md"
+    echo "  2. 按 $TARGET/BOOTSTRAP.md 走一遍铸魂"
+    ;;
+  memory-only)
+    echo "接下来：直接开始记东西就行，不用管性格。"
+    echo "  · 注入会自动跳过空的 SOUL"
+    echo "  · 想改主意：把 $TARGET/BOOTSTRAP.md 的 status 改回 pending"
+    ;;
+  external)
+    echo "接下来：性格由你自己的 agent prompt 负责，这里只管记忆。"
+    echo "  · 注入只有 index.md + NOW.md"
+    ;;
+esac
+echo "  · 建索引：python3 $MEMKIT_ROOT/brain/index.py"
+echo "  · 起服务：bash $MEMKIT_ROOT/bin/serve"
+echo "  · 看注入：soul-boot --list"

package/lib/plugin.js

@@ -23,7 +23,25 @@ const HERE = dirname(fileURLToPath(import.meta.url))
 const KIT_ROOT = resolve(HERE, '..')
 
 // 注入顺序：先是谁，再是什么规矩，再是目录，最后是此刻。
-const PARTS = ['SOUL.md', 'MEMORY.md', 'index.md', 'NOW.md']
+const ALL_PARTS = ['SOUL.md', 'MEMORY.md', 'index.md', 'NOW.md']
+
+// 三种模式 —— 跟 soul.py 里的 MODES 保持一致
+const MODES = {
+  full: ALL_PARTS,
+  // 不要性格：空 SOUL 塞进去比不塞更糟（模型会看到"我的名字是（待填）"）
+  'memory-only': ['MEMORY.md', 'index.md', 'NOW.md'],
+  external: ['index.md', 'NOW.md'],
+}
+
+// 空模板检测：占位符够多就跳过，别把模型带偏
+const PLACEHOLDER_MARKS = ['（待填', '(待填', 'TODO', '（示例', '（还没有']
+const PLACEHOLDER_MIN = 3
+
+function isPlaceholder(body) {
+  let n = 0
+  for (const m of PLACEHOLDER_MARKS) n += body.split(m).length - 1
+  return n >= PLACEHOLDER_MIN
+}
 
 function defaultMemoryDir() {
   // 不放在 node_modules 里——升级插件会把那里整个换掉。
@@ -41,13 +59,19 @@ function readIf(p) {
 /**
  * 拼注入块。budget 是字数上限，超了从末尾截（先保 SOUL）。
  * 注意：这里是**字符数**，不是字节数。
+ *
+ * files      指定要哪些文件（优先级高于 mode）
+ * mode       full / memory-only / external
+ * skipEmpty  自动跳过仍是空模板的页（默认开）
  */
-export function bootBlock(memoryDir, budget = 20000) {
+export function bootBlock(memoryDir, budget = 20000, { files = null, mode = 'full', skipEmpty = true } = {}) {
+  const parts = files && files.length ? files : MODES[mode] || ALL_PARTS
   const chunks = []
   let total = 0
-  for (const name of PARTS) {
+  for (const name of parts) {
     const body = readIf(join(memoryDir, name))
     if (!body) continue
+    if (skipEmpty && isPlaceholder(body)) continue
     let block = `<!-- ${name} -->\n${body}`
     if (total + block.length > budget) {
       const left = budget - total
@@ -59,7 +83,7 @@ export function bootBlock(memoryDir, budget = 20000) {
     chunks.push(block)
     total += block.length
   }
-  if (!chunks.length) return ''
+  if (!chunks.length) return '（记忆库还是空的，暂时没有可注入的内容。）'
   return (
     '下面是你的长期记忆。你确实记得这些事，像想起往事一样自然地用，' +
     '不要说「根据记忆库」「据记录」这类话。\n\n' + chunks.join('\n\n')
@@ -106,6 +130,10 @@ const SKILL = {
 export function apply(ctx, config = {}) {
   const memoryDir = config.memoryDir || defaultMemoryDir()
   const budget = Number(config.bootMaxChars || 20000)
+  // 模式：full / memory-only / external；bootFiles 可直接指定文件名单
+  const mode = config.mode || 'full'
+  const files = Array.isArray(config.bootFiles) && config.bootFiles.length ? config.bootFiles : null
+  const skipEmpty = config.skipEmptyTemplates !== false
 
   const disposers = []
 
@@ -115,7 +143,7 @@ export function apply(ctx, config = {}) {
       ctx.systemPrompt.context({
         name: 'soul-boot',
         order: -200,
-        text: () => bootBlock(memoryDir, budget),
+        text: () => bootBlock(memoryDir, budget, { files, mode, skipEmpty }),
       }),
     )
   }
@@ -135,7 +163,7 @@ export function apply(ctx, config = {}) {
     }
   }
 
-  ctx.logger?.info?.(`[soul-forging] 记忆目录：${memoryDir}（上限 ${budget} 字）`)
+  ctx.logger?.info?.(`[soul-forging] 记忆目录：${memoryDir}（模式 ${mode} · 上限 ${budget} 字）`)
 
   return () => {
     for (const d of disposers) {
@@ -152,4 +180,4 @@ apply.inject = inject
 export default apply
 
 // 给测试用：不装插件也能直接看注入块长什么样
-export { PARTS, KIT_ROOT }
+export { ALL_PARTS, MODES, KIT_ROOT }

package/memory/BOOTSTRAP.md

@@ -1,5 +1,5 @@
 ---
-status: pending
+status: pending   # pending 还没定 / complete 定完了 / skip 明确不要性格
 ---
 
 # BOOTSTRAP — 铸魂
@@ -37,7 +37,9 @@ status: pending
 
 ## 规则
 
-1. `status` 未变成 `complete` 时，每次会话开始的头一件事是**继续这个对话**，不埋头做别的。
+0. **`status: skip` 时整份清单作废**——用户明确说了不要性格，别再问他"你叫什么名字"。
+   什么时候想动了，把 status 改回 `pending` 就重新生效。
+1. `status` 未变成 `complete`（且不是 `skip`）时，每次会话开始的头一件事是**继续这个对话**，不埋头做别的。
    主人明确说要先干别的，就照做，但之后要回来。
 2. 一次推进一项。**不要一口气问完**——那是问卷，不是聊天。
 3. 写回文件之后才勾选，顺序不能反。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-soul-forging",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Separate Vessels, One Heart · 异体同心 —— 给 AI 的可迁移长期记忆与铸魂流程：markdown 记忆库 + 小脑检索 + 能长出来的性格。纯本地，不要服务器。",
   "license": "MIT",
   "type": "module",

package/scripts/smoke.sh

@@ -90,15 +90,38 @@ run "soul-debug"     "$BIN/soul-debug"
 echo "== 4. 包目录必须干净（跑完所有命令之后查）=="
 DIRTY=$(check_pkg_clean) && ok "包目录没被写脏" || bad "包目录被污染：$DIRTY"
 
-echo "== 5. 插件加载 =="
+echo "== 5. 三种模式（不想改性格的人）=="
+# memory-only：不该生成 SOUL，注入里不该出现性格
+export MEMORY_DIR="$TMP/mem2"
+"$BIN/soul-init" --memory-only >/dev/null 2>&1
+[ ! -f "$MEMORY_DIR/SOUL.md" ] && ok "memory-only 不生成 SOUL.md" || bad "memory-only 还是生成了 SOUL"
+grep -q "^status: skip" "$MEMORY_DIR/BOOTSTRAP.md" 2>/dev/null && ok "memory-only 把铸魂标成 skip" || bad "memory-only 铸魂还停在 pending（会反复催）"
+"$BIN/soul-boot" --mode memory-only --list 2>&1 | grep -q "不注入（模式）" && ok "memory-only 不注入 SOUL" || bad "memory-only 仍在注入 SOUL"
+# external：连 BOOTSTRAP 都不铺
+MEMORY_DIR="$TMP/mem3" "$BIN/soul-init" --external >/dev/null 2>&1
+[ ! -f "$TMP/mem3/BOOTSTRAP.md" ] && ok "external 不铺铸魂清单" || bad "external 还铺了 BOOTSTRAP"
+MEMORY_DIR="$TMP/mem3" "$BIN/soul-boot" --mode external 2>&1 | grep -q "记忆库还是空的" && ok "external 空库时不硬塞东西" || bad "external 空库仍注入了内容"
+# 空模板保护：没填的 SOUL 不许进上下文
+MEMORY_DIR="$TMP/mem2" "$BIN/soul-boot" --keep-empty 2>&1 | grep -q "（待填" && ok "占位符确实存在（对照）" || true
+MEMORY_DIR="$TMP/mem2" "$BIN/soul-boot" 2>&1 | grep -q "（待填" && bad "空模板被注入了" || ok "空 SOUL 不会进上下文"
+unset MEMORY_DIR
+
+echo "== 6. 插件加载 =="
+export MEMORY_DIR="$TMP/home/.soul-forging/memory"
 node -e "
 import('$PREFIX/lib/node_modules/dsh-soul-forging/lib/plugin.js').then(m=>{
-  let c; const ctx={systemPrompt:{context(o){c=o;return()=>{}}},skills:{register(){return()=>{}}},logger:{info(){},warn(){}}};
-  m.apply(ctx,{});
-  const t=c.text({});
+  const memoryDir = process.env.MEMORY_DIR;
+  let c;
+  const ctx = {systemPrompt:{context(o){c=o;return()=>{}}}, skills:{register(){return()=>{}}}, logger:{info(){},warn(){}}};
+  m.apply(ctx, memoryDir ? {memoryDir} : {});
+  const t = c.text({});
   if(typeof m.name!=='string') throw new Error('name 缺失');
   if(!Array.isArray(m.inject)) throw new Error('inject 缺失');
-  if(!t || t.length<1000) throw new Error('注入块太短: '+t.length);
+  if(!t || t.length<100) throw new Error('注入块太短: '+t.length);
+  const mm = m.bootBlock(memoryDir, 20000, { mode: 'memory-only' });
+  const ee = m.bootBlock(memoryDir, 20000, { mode: 'external' });
+  if(typeof mm!=='string' || typeof ee!=='string') throw new Error('模式参数不可用');
+  if(ee.includes('小蓝') && !t.includes('小蓝')) throw new Error('模式串了');
   console.log('OK '+t.length);
 }).catch(e=>{console.log('FAIL '+e.message);process.exit(1)})
 " >/tmp/smoke-plugin.out 2>&1

package/soul.py

@@ -2,16 +2,26 @@
 # -*- coding: utf-8 -*-
 """接线层：把记忆库接进任何 agent（dsh-soul-forging）。
 
-两种用法：
+三种用法：
 
-  ① 命令行（最简单，任何语言都能调）
-       soul-boot                打印开局注入块
-       soul-boot --budget 12000 限制字数（超了从末尾截）
-       soul-boot --list         看各部分多长
+  ① 命令行
+       soul-boot                     打印开局注入块
+       soul-boot --budget 12000      限制字数（超了从末尾截）
+       soul-boot --list              看各部分多长、哪些被跳过
+       soul-boot --mode memory-only  只要记忆，不要性格
+       soul-boot --with index.md,NOW.md   自己挑要哪些文件
 
   ② 当模块用（Python）
-       from kit import boot, recall, remember
-       sys_prompt += boot()
+       from soul import boot, recall, remember
+       sys_prompt += boot(mode="memory-only")
+
+  ③ 直接读文件
+       就是那四个 markdown，自己拼也行
+
+三种模式：
+  full         四个文件全注入（默认）—— 想长性格的人
+  memory-only  不注入 SOUL —— 只要记忆、不想动性格的人
+  external     只注入 index + NOW —— 性格交给你自己 agent 的 prompt
 
 设计原则：**只读，不写**。注入不产生副作用；要写记忆走 remember()。
 """
@@ -23,7 +33,19 @@ DATA_ROOT = os.environ.get("SOUL_DATA_DIR") or os.path.join(os.path.expanduser("
 MEM = os.environ.get("MEMORY_DIR") or os.path.join(DATA_ROOT, "memory")
 
 # 注入顺序就是重要性顺序：先是谁，再是什么规矩，再是目录，最后是此刻。
-PARTS = ("SOUL.md", "MEMORY.md", "index.md", "NOW.md")
+ALL_PARTS = ("SOUL.md", "MEMORY.md", "index.md", "NOW.md")
+
+MODES = {
+    "full": ALL_PARTS,
+    # 不要性格：SOUL 不注入。空模板塞进去比不塞更糟——模型会看到"我的名字是（待填）"
+    "memory-only": ("MEMORY.md", "index.md", "NOW.md"),
+    # 性格归你自己的 agent：我们只管目录和此刻
+    "external": ("index.md", "NOW.md"),
+}
+
+# 判断"这页还是空模板"：占位符太多就别注入，省的把模型带偏
+PLACEHOLDER_MARKS = ("（待填", "(待填", "TODO", "（示例", "（还没有")
+PLACEHOLDER_MIN = 3
 
 
 def _read(name):
@@ -35,26 +57,41 @@ def _read(name):
         return ""
 
 
-def boot(budget=None, parts=PARTS, header=True):
-    """拼出开局注入块。budget 是字数上限（None = 不限制）。"""
+def is_placeholder(body):
+    """空模板检测：占位符出现次数够多，就当这页还没填。"""
+    return sum(body.count(m) for m in PLACEHOLDER_MARKS) >= PLACEHOLDER_MIN
+
+
+def boot(budget=None, parts=None, header=True, mode=None, skip_empty=True):
+    """拼出开局注入块。
+
+    budget      字数上限（None = 不限制）
+    parts       指定要哪些文件（优先级高于 mode）
+    mode        full / memory-only / external
+    skip_empty  自动跳过还是空模板的页（默认开）
+    """
+    use = tuple(parts) if parts else MODES.get(mode or "full", ALL_PARTS)
     chunks = []
     total = 0
-    for name in parts:
+    for name in use:
         body = _read(name)
         if not body:
             continue
-        # 每块加个小标题，方便模型分辨
+        if skip_empty and is_placeholder(body):
+            continue
         block = f"<!-- {name} -->\n{body}"
         if budget is not None and total + len(block) > budget:
             left = budget - total
             if left > 200:            # 剩一点就截，剩太少就整块不要
-                block = block[:left] + "\n…（本块超预算被截断）"
-                chunks.append(block)
-                total += len(block)
+                chunks.append(block[:left] + "\n…（本块超预算被截断）")
+                total += left + 20
             break
         chunks.append(block)
         total += len(block)
     body = "\n\n".join(chunks)
+    if not body:
+        # 什么都没填时不硬塞一句空话，明说
+        return "（记忆库还是空的，暂时没有可注入的内容。）" if header else ""
     if not header:
         return body
     return (
@@ -91,16 +128,37 @@ def _main(argv):
     budget = None
     if "--budget" in argv:
         budget = int(argv[argv.index("--budget") + 1])
+    mode = None
+    if "--mode" in argv:
+        mode = argv[argv.index("--mode") + 1]
+        if mode not in MODES:
+            print(f"不认识的模式：{mode}（可选：{', '.join(MODES)}）")
+            return 1
+    parts = None
+    if "--with" in argv:
+        parts = tuple(x.strip() for x in argv[argv.index("--with") + 1].split(",") if x.strip())
+    skip_empty = "--keep-empty" not in argv
+
     if "--list" in argv:
-        for name in PARTS:
+        use = parts or MODES.get(mode or "full", ALL_PARTS)
+        print(f"模式：{mode or 'full'}")
+        for name in ALL_PARTS:
             body = _read(name)
-            print(f"{name:16s} {len(body):6d} 字 {'✓' if body else '（空）'}")
-        print(f"{'合计':16s} {sum(len(_read(n)) for n in PARTS):6d} 字")
+            if name not in use:
+                tag = "不注入（模式）"
+            elif not body:
+                tag = "（空）"
+            elif skip_empty and is_placeholder(body):
+                tag = "空模板，已跳过"
+            else:
+                tag = "✓"
+            print(f"  {name:16s} {len(body):6d} 字  {tag}")
         return 0
+
     if "--bare" in argv:
-        print(boot(budget=budget, header=False))
+        print(boot(budget=budget, parts=parts, header=False, mode=mode, skip_empty=skip_empty))
         return 0
-    print(boot(budget=budget))
+    print(boot(budget=budget, parts=parts, mode=mode, skip_empty=skip_empty))
     return 0