Name: lingshu-skill (lingshu-startup)
Author: 266767398

灵枢 · 类脑记忆、人格与成长

名字取自《黄帝内经》：算力给思考，人格给灵魂，记忆给生命。

当前版本 v2.35（变更见 CHANGELOG.md）

🔁 双仓库镜像：GitHub（主）与 Gitee（镜像）保持同步——gitee.com/htmcwy_0/lingshu-skill。灵枢的更新检查会探测两边最新提交，谁更新就自动从谁拉取；任一边不可达（Gitee 匿名风控 / GitHub 限额）时走另一边兜底。

⚠️ 能力天花板（先读）：灵枢是「提示词 + 脚本」的机制，不能从底层强制约束模型。当模型发生强幻觉时依然会无视全部规则；效果上限取决于底层大模型本身的推理、记忆与指令遵循能力。中强模型（7B+、云端）可完整遵守；3B 以下本地小模型会出现大量规则漏执行（忘走 startup、跳过写盘、纪律打折）——请据此降低预期，或改用 SKILL-lite.md（精简版）/ SKILL-tiny.md（最小试用版）。

🚨 风险警告：幻觉会被固化落盘。本地保存 ≠ 内容真实。dream、knowledge tidy、emotion evaluate 都要大模型产出结构化结果；模型若把无关记忆强行合并、编造内容、误判情绪，这些错误会被持久写进本地记忆库 / 知识库，不会自动消失。防护措施：AI 动过的记忆 / 知识一律先标为待审核（review → confirm / discard；知识也可 knowledge review），人格变更带来源与依据（persona history），另有全局自查 audit。小模型请用 config set model_tier small 关掉高风险自动能力。审核闸由 AI 自审在前：AI 产物先过目、确认后才算数；用户用 audit / review 随时复核介入。

一套纯本地、零依赖（只用 Python 标准库）的 AI 记忆系统。它把"上下文窗口"变成"会生长的记忆"——短期记忆像海马体一样快速写入、自然衰减；上下文将满时像人做梦一样重放、压缩、巩固到长期皮层；想不起来时靠模糊联想而不是精确匹配。

核心机制
- 分层记忆与遗忘曲线
- 做梦：上下文将满时的整理
- 上下文水位三级防线
- 工作记忆
- 会话模式与情绪隔离
- 审核闸：AI 产物先过目，AI 自己审
情绪与类人机制
模糊联想回忆
记忆关联（联想图谱）
人格
成长路径
- 知识库
- 笔记日志
- 技能自编辑与全局化
- 进化日志
DeepSeek 生态兼容
cordis 插件：启动自动注入
可视化面板
- 自定义面板与面板市场
多群/多会话：通道三元组（v2.34）
- 群友隐私保护（v2.35）
AstrBot 插件（v2.35）
可靠性设计
脚本 vs 模型：谁在真正干活
模型适配与档位
接入大模型（Ollama 示例）
规模上限与归档
如何更新灵枢
快速开始
命令速查
项目结构

核心机制

分层记忆与遗忘曲线

记忆分三层，模拟大脑：

层	作用	衰减
海马体（hippo）	短期：新写入的记忆，快速衰减	快（按访问衰减）
皮层（cortex）	长期：做梦/多次访问后巩固上来	慢
淡忘区（dust）	久未访问、重要性低，自然遗忘	只留残余
归档层（archive）	沉眠记忆雪藏（保留度 <0.2、重要度 ≤0.5、满月且长期没被想起）：原文一字不丢，移出热查询集，`recall` 默认不查	不衰减，可 `archive restore` 回热

每条记忆按艾宾浩斯遗忘曲线衰减，但访问会加固（recall 命中即强化），重要性高的记忆衰减更慢，被置顶（pinned）的记忆永不遗忘。冷热自动归档：每次做梦时顺带把沉眠记忆雪藏进 archive 层（也可 archive run 手动），上万条记忆后热遍历集只扫活跃记忆——回忆速度不随记忆增长而变慢，需要时 archive search / recall --include-archive / archive restore 随时找回。

做梦：上下文将满时的整理

上下文超过 75% 时触发"做梦"——灵枢重放短期记忆、按主题合并碎片、巩固到长期皮层，并把不重要的淡忘。梦完成后输出一份报告，告诉你巩固了什么、淡忘了什么、哪些还没想明白。

dream --auto：内置自愈——重放 → 启发式合并 → 沉淀，不依赖任何外部脚本。
手动三步：dream --trigger context → 读 pending 填 apply.json → dream --apply apply.json。面板梦页可直接网页编辑草稿（dreams/apply_draft.json）再 apply，不必命令行改文件。

上下文水位三级防线

会话中即记即存，不攒到做梦。 约定、情绪高点、里程碑当时就 remember；上下文快满时原文封存：

水位	动作	命令
随时	即记即存	`remember` / `capture`
60%	主动清点：本轮还有哪些该记没记，先补记	`check-context --used 60`
75%	做梦：重放→压缩→巩固	`dream --auto`
90%	逃生：原样封存，先保命再压缩	`capture "原文" --tag 逃生`

capture 保证 100% 不丢：原文归档到 verbatim/（逐字不改，保险柜）+ 逐段进记忆库并打 verbatim 标记（做梦永不淡化、永不进淡忘区）。

工作记忆

当前上下文本身就是工作记忆，默认不落盘。只有需要留一手时才 work add（会话级暂存，最多 9 条，12 小时后自动丢）。每件带"未完成/已完成"状态（蔡格尼克效应）：没做完的事会在注入包里被点名"还惦记着"，做完用 work done <序号> 标记就放下；work flush 把值得留的转成真正记忆（--skip-done 只转没完成的，已 done 的直接丢），work clear 丢掉。

会话模式与情绪隔离

工程会话和日常聊天的需要是打架的：刚聊完情绪化话题转头写代码，旧情绪的余波还在注入包里，模型容易被带着走偏。灵枢用 mode 切三种会话模式（config.mode，默认 auto）：

work 工程模式：情绪状态与拟人语气不注入本会话，注入包明确说"旧情绪与当前任务无关，当作没有"，先给可执行方案，重视正确性与工程契约。
human 拟人模式：情绪照常注入，并把数值得翻成可直接照着做的行为约束（emotion now 不再只有裸数字）。
auto 自动模式（默认）：打分制话题判定——工程信号（编程/数据/工程三组 26 词）与人性信号（情绪/关系/寒暄三组 30 词）分组计数打分，work_score >= human_score 工程优先。一边聊天一边写代码也不会轻易切错：句子里有代码、报错就偏 work，情绪词再多也按"工程优先"隔离；两侧都命中时判定标 mixed 并把依据摊开。判定可见：面板概览有「会话模式判定」卡（当前模式、置信度、两侧分数、命中词、可输入一句话试判），CLI 用 mode explain "一句话话题" 看同款依据。

切换：mode work | human | auto。写代码前想手动清掉余波，用 emotion cool 把 24 小时内的强情绪整体降温，或 emotion adjust <序号> 微调单条。

审核闸：AI 产物先过目，AI 自己审

记忆→做梦→知识库→进化日志→人格，这条链路里 AI 既是整理者又可能编造者，幻觉会逐层沉淀污染人格。灵枢给每个 AI 动手的环节都加了审核闸——AI 产物必须先过目，确认后才算数，而不是模型产出后直接落盘：

AI 整理的记忆（dream --apply 等）标 review="pending"，确认前不算事实。
AI 整理的知识（knowledge tidy）标 status="pending"。
AI 发起的人格变更记 source（dream/自我总结/…）与 evidence（依据的记忆/事件 id），persona history 可溯源。
审核由 AI 自审：AI 每会话先看 review（全部待审项）→ review confirm <id> 转正 / review discard <id> 废弃（记忆 m_* 与知识 k_* 通用，后者等同 knowledge confirm/discard）；整体自查用 audit（待审计数 + 冲突记忆 + 该做什么）。注入包一出现 [待审核] / [人格漂移] 就先处理再继续。
用户随时可介入：人工复核走同一套命令即可，不用把用户变成质检员——AI 自审在前，人在必要处兜底。面板记忆页支持多选批量 confirm/discard、批量改重要性/打标签，大量待审条目不必逐条点。

每个会话的注入包会主动提醒有 [待审核] 项、有 [人格漂移]，不让幻觉静默沉淀。

情绪与类人机制

情绪系统把"心情"做成一条会衰减的曲线，而不是一行写死的字：

两条轴：valence（喜/哀，-1~~1）+ arousal（强度，0~~1），用半衰期叠加算出此刻心情（emotion now），看轨迹用 emotion arc，情绪共 7 大类（emotion list）。
怎么产生情绪：emotion evaluate 认知评价自动产生（不是手动演出来的）、emotion mirror 共情跟入用户情绪、emotion feel 手动记一笔。共情强度与抑制清单是用户随时可改的设定（emotion config）。
错判了能微调：emotion events 看事件流（带序号），emotion adjust <序号> 只改判错的那几项（强度/情绪名/原因），emotion del <序号> 删掉误记的整条，不用推倒重来。
情绪增强编码：情绪强烈时记住的事更牢，记录带 emotion 标记（杏仁核打个标签）。
情绪传染 / 心情惯性：新情绪会被当下心情"染色"——同向被点燃放大，反向被惯性往回拽，不会瞬间反转。
习惯化 / 享乐适应：同一件事反复出现，情绪反应递减；反复记的同一件事重要性也不再步步抬升（但保留下限）。
杏仁核劫持：情绪最强烈时理智权重被压下，但上限封在 40%——再上头也得给人留余地。
峰终定律：对一段体验的记忆，几乎只由"最强烈的一刻"和"结尾"决定，情绪总结按这个口径出。
首因效应：最早留下的印象占权更高，首次被想起的记忆强化更深。
情绪-输出一致性核对：emotion check "回复文本" 做后置轻量校验——内部情绪强度足够、而回复语气与内部数值严重背离时告警（落 emotion_checks.jsonl，面板心情页可看最近告警），防止"心里难过却满口欢快"的违和。

模糊联想回忆

recall 不靠精确匹配：中文用字符二元组、英文/数字用词做模糊联想，按 相关度 + 近期性 + 重要性 + 首因 加权排序（另带时效软加权：越久的记忆按半衰期 30 天轻微降权，地板 0.5——旧事实不会沉底，新变化优先浮现），并在命中后自动强化（越用越牢）。数字/编号被保留为独立词元，不会把"版本0"和"版本1"误当成同一条。

上万条也不慢：带查询词时先用子串包含预筛剪枝候选（查询词必是来源文本连续子串，数学上不丢召回），只对命中候选做分词打分；无查询词（startup 注入）直接走快速路径，不再构建全量词表。实测 1 万条记忆 recall 从约 3.5s 降到 76ms（约 47 倍），remember 约 100ms。

记忆关联（联想图谱）

模糊回忆靠"字面像不像"，但人脑还会靠联想串记忆："A 导致了 B""提到 A 就想起 C"。灵枢把这些关系存成显式关联边（assoc.jsonl，无向，带关系名与权重）。recall 命中一条记忆时，会沿关联边把邻居也带起来（联想扩散），关联越重带得越明显。

怎么手动建立关联（完整示例）

# 1) 先建两条记忆，记下各自的 id（remember 会打印 id，如 m_3f2a...）
python scripts/brain.py remember "服务器崩了是因为内存泄漏" --kind fact --importance 8
python scripts/brain.py remember "把 JVM 堆从 2G 调到 4G 之后不再崩" --kind fact --importance 7

# 2) 手动连线：idA idB --relation 关系名 --weight 权重 --why 为什么
python scripts/brain.py assoc link m_3f2a... m_9c1d... --relation "因果" --weight 1 --why "调堆是内存泄漏的缓解结果"

# 3) 看这条记忆连着什么
python scripts/brain.py assoc of m_3f2a...

# 4) 懒人补网：按共享实体/标签自动成边（先 --dry-run 预览要连哪些）
python scripts/brain.py assoc auto --dry-run
python scripts/brain.py assoc auto

# 5) 看整张网（节点数 / 边数 / 有多少节点被连成网）
python scripts/brain.py assoc graph --limit 300

# 6) 连错了就断开
python scripts/brain.py assoc unlink m_3f2a... m_9c1d...

要点

关系名随你定：因果 / 相关 / 情绪 / 反例 都行；同一对记忆反复 link 会加重（权重上限 3），越常被想起的联想越强。
不用背 id：面板记忆页每条卡片底部直接显示 id xxx，复制即可；也可用 list / recall 结果里的 id。
面板看网络：serve 后进「联想」页——每条记忆一个节点、连线是关联的 3D 空间（虚空星图），拖拽旋转、滚轮缩放、点节点看详情与邻居；页面顶部还有「手动建立关联」卡，填 A/B 的 id + 关系名 + 为什么，一键连上，不用命令行。
没显式连过也能看：assoc auto 会按共享实体/标签先补一批边，让图先"长"出来；再按需手动精修。

人格

人格不预写。第一次使用时问用户"你希望我叫什么、是什么性格"，用户说不知道就由灵枢自己定。喜好、厌恶、习惯由相处中自己写。

人格演化有完整历史，每次改动可回滚：persona history 看历史（序号从最新往前数，条目带来源 source 与依据 evidence，能看清这次改人格来自哪段对话/哪些记忆），persona rollback <序号> 一键撤销那次改动；回滚本身也记一条历史。
快照与漂移告警：重要节点先 persona snapshot --label "基准" 拍一张完整快照；persona snapshots 列表、persona restore <名字> 一键还原。persona drift 把当前人格与最近基准快照逐字段对比（结构差异 + 最近 N 天 AI 改动，--days 可调），变化偏大时注入包会亮 [人格漂移] 告警——微小偏移也看得见，不是等跑偏了才发现。
好奇心与理智是两条内驱数值，不是出厂设定——用户嫌你啰嗦，理智上调；用户让你多挖多试，好奇心上调（mind tune）。它们不是只有裸数值：注入包（startup 的 human 模式块）会把数值翻成行为约束（_behavior_map），模型照做即可。
persona self 让你总结"我是谁"，persona interview 是初识引导。

成长路径

知识库

把经历提炼成可复用的结论（不是流水账）。每条有主题、观点、要点、相关记忆引用，支持置顶与版本更新。knowledge tidy 会提示你哪些经历值得提炼成知识——AI 动过的条目一律先标为待审核（面板里直接看，或 knowledge review 查看），由 AI 自审 knowledge confirm <id> / knowledge discard <id> 转正/废弃（用户可随时介入复核），防止模型幻觉直接沉淀成知识库。

笔记日志

写给自己的日记（journal）、工作日志（log）、成长复盘（growth）。note digest --days 7 定期回看自己写了什么。

技能自编辑与全局化

技能是固化的做法：skill new 写 → skill check 自检 → skill install 装进全局技能目录（~/.trae-cn/skills/），新会话直接可调。skill use --auto 用技能时自动全局化；skill borrow 借鉴别人的技能变成自己的版本（诚实标注来源）。支持中文技能名。

跨宿主技能发现（v2.23）：灵枢会只读扫描本机各 AI 工具的全局技能目录（DSH、Trae CN/Trae、Claude Code、Codex、Cursor、Gemini 等 15 个候选），skill roots 看哪里有技能、skill scan 列出可复用的、skill use 照做、skill borrow 借为己用。也可以用 skill root-add <路径> 手动添加目录，或设环境变量 LINGSHU_GLOBAL_SKILLS（多个用 ; , 分隔）。面板「技能」页同样能看/加根目录并重扫。技能有两种形态：skill 是说明书（给人/别的 AI 复用）；ext（扩展模块）是 AI 自己写进灵枢引擎的可执行 Python 钩子（inject 并入每会话注入、run 加自定义命令），放在数据目录 ~/.brain-memory/extensions/，更新永不覆盖、坏模块自动跳过。

进化日志

每次真正的改进（人格微调、技能新增、知识沉淀、思维变化）记进进化日志 evolve log，是灵枢的成长史。

DeepSeek 生态兼容

整目录全局化：带 scripts/、assets/ 的技能整目录复制进全局目录，副本能直接跑。
自动生成 AGENTS.md：DSH/DeepSeek 以 AGENTS.md 为常驻入口（每次会话必进上下文），安装时自动生成「何时用 / 怎么用 / 入口命令」。
DSH 插件只读可见：skill plugins 列出 ~/.dsh/profiles 下所有 DSH 插件（名字、版本、描述、AGENTS.md 标记），面板也有专属区块——只看不改。
frontmatter 解析健壮：支持引号、多行块标量，各家写的 SKILL.md 都能读对。

cordis 插件：启动自动注入

技能 catalog 只把 name + description 给模型，正文要不要读全凭模型"自觉"——没有任何机制保证下一次会话模型一定会加载灵枢。cordis-plugin/ 里的插件把"自觉"变成"机制"：

lingshu-startup：监听 DSH 的 agent/created 事件（source ∈ startup / resume），自动探测全局技能目录里的 scripts/brain.py，跑 startup 并把人格、记忆、待办、行为指引以 UserMessage 形态 agent.inject() 进会话上下文——会话一开始记忆就在上下文里。clear / compact 不重复注入，进程内按 agent 去重。
失败宽容：灵枢没装、Python 不在、超时——全部静默跳过，绝不阻塞会话； brain.py startup 只读记忆库，HOME 不可写时自动只读降级照样注入。 装完插件必须完全重启 DSH——Host 的插件树（cordis bundles）是主进程启动时一次性组合的，不重启新会话感知不到（skill catalog 走 chokidar 热更新，插件不是）。
目录约定：cordis-plugin/ 下一个插件一个子目录，各自独立打包安装，互不干扰。详见 cordis-plugin/lingshu-startup/README.md。

可视化面板

brain.py serve 启动本地面板（仅监听 127.0.0.1，start-panel.bat 一键启动）：

记忆浏览：层 + 重要性区间 + 时间范围 + 标签 + 情绪 + 排序的组合筛选；置顶、编辑、忘记
批量操作：多选（含全选）后一次批量 confirm/discard 待审核条目、批量设重要性、批量加/减标签
注入包预览：直接看 startup 会注入给模型的完整记忆包（只读，不落盘、不加强记忆）
冲突检查：启发式扫出"可能矛盾/已过时"的记忆对，只提醒不下结论； 冲突裁决队列——AI 整理出的新说法与旧记忆矛盾时不静默覆盖，双方互标冲突待人工裁决（review confirm 才落实取代、discard 恢复旧说法）；用户亲口说的仍即时生效
会话模式判定卡：当前模式 + 置信度 + 工程/情绪两侧分数 + 命中词依据，可输入一句话试判 auto 会怎么切
人格、内驱数值实时查看与微调；人格历史可一键回滚
知识库（含 ⏳待审核 / 已确认 / 已废弃 状态，可 confirm/discard）、笔记、技能（含 DSH 插件区块）、成长、进化日志；知识条目带证据分级 E0-E4（knowledge verify 记一次验证等级+1，E4 封顶，检索时验证过的优先）
心情页：情绪-输出一致性核对（输入回复看语气与内部情绪是否背离 + 最近告警）、七情/六欲/认知评价/共情
联想页（3D 星图）：记忆网络可视化 + 手动建立关联卡（填 A/B id 一键连线）
做梦报告（改库前自动打快照回滚点，梦错了可还原）、网页编辑 apply 草稿再 apply、备份恢复
日志页：锁冲突 / 内部异常 / 解析报错按级别查看，不用再去翻本地日志文件
只读降级有醒目横幅：目录不可写时页面顶部直接提示"修改不会保存"

安全：面板自带随机 token 鉴权（页面加载时注入，所有 API 请求必须携带），并校验 Host/Origin，挡住 DNS rebinding 与无来源直连偷读记忆。

自定义面板与面板市场

自定义面板系统——默认面板之外，可整套换皮而不动引擎：

热加载切换：面板放进 ~/.brain-memory/panels/<面板名>/ 即被识别，在面板管理菜单里一键启用/删除/上传，切换即时生效，不用重启服务；
本机共享市场：~/.brain-memory/panel-market/ 是本机市场目录——拷一个面板目录进去就能流通，其他 AI 宿主、其他项目里打开面板市场都能看到并安装；
损坏自动回退：自定义面板代码出错 / 文件损坏 / 目录缺失时自动回退默认面板，记忆引擎与其他功能完全不受影响；
AI 可直接开发：AI 按 docs/panel-api.md 规范（页面结构、API 清单、鉴权方式）就能写一个完整面板；或让 AI 调 /api/panels/scaffold 一键生成骨架再改。

云端面板市场（v2.29+）：面板除了本机流通，还能发布到你自己的 Gitee 公开仓库（可选 GitHub 镜像），别人打开面板市场就能看到截图、描述并一键下载安装。注意：发布（上传/更新）必须有对应平台的仓库账号和私人令牌——Gitee 在 gitee.com「设置→私人令牌」生成（勾 projects 权限），GitHub 在 github.com/settings/tokens 生成；令牌只存本机 config.json，不会上传、不会出现在接口响应里。浏览/下载别人的面板不需要任何令牌。这些信息 AI 都会在你提到"做面板/发面板"时主动讲清楚，也可以直接把你的仓库名和令牌告诉 AI，让 AI 在面板里替你配置好。

多群/多会话：通道三元组（v2.34）

当灵枢同时服务多个群聊 / 多个会话时，记忆默认混在一起会串台。v2.34 引入通道三元组（channel / group_id / user）做记忆隔离与跨群共享：

同一群共用一份群记忆：group_id 相同的会话共享群级记忆（群规、群梗、共同的约定）；每个用户自己说过的话另存用户层，互不污染。
跨群记忆：channel remember / channel recall 操作"全局通道"记忆——想在所有群/会话间共享的记忆（你的偏好、主人的规则）写进这里，哪个群都能想起来。
按人回忆：channel user <id> 回忆某个用户在群里说过的事——做群管、画像、个性化回应都用得上。
startup 注入自动带上通道：会话在哪个群、以谁的身份启动，注入包就是那个通道的视角；主记忆库（startup 不带通道）仍是全局兜底。

群友隐私保护（v2.35）

群聊里不只有你一个人——把别人的话记进记忆库并让 AI 拿去回忆，本质是拿别人的数据。v2.35 加了一道本人授权门控：

本人可查可删：任何用户可以查看自己被记了什么（channel privacy status 看自己）、要求删除；
第三人需授权：回忆/查询别人在群里说的内容，需要对方曾用 channel privacy grant 授权过（按用户维度记录在 consent.json）；未授权时命令被拒（退出码 4，PrivacyDenied），并明确告知哪位用户未授权；
主人也不豁免隐私门控：owner/admins 只能管理命令（授权/撤销/查看状态），不能替别人授权自己去看——隐私门控对所有人一致；
随时撤销：channel privacy revoke <用户> 撤销授权，之后该用户的数据立即回到"第三人不可查"状态。

命令速查：

命令	作用
`channel remember "内容" --group <id> [--user <id>]`	写群级/用户级记忆
`channel recall "关键词" --group <id>`	从指定群通道回忆
`channel user <id>`	回忆某用户在群里的记录
`channel privacy status [--user <id>]`	查看自己/指定用户的授权状态
`channel privacy grant <用户>`	本人授权（同意被记忆与被回忆）
`channel privacy revoke <用户>`	撤销授权

主人鉴权（v2.34）

config.json 里配置 owners（主人）与 admins（管理员）名单后，危险/管理类命令只对名单内身份放行：非主人执行管理命令返回退出码 3，避免群里任何人都能指挥灵枢改人格、删记忆。主人/管理员名单只存本机，不上传。

AstrBot 插件（v2.35）

除 DSH / Trae 之外，灵枢还提供了一个 AstrBot 插件（scripts/astrbot_plugin_lingshu/），把灵枢接进 AstrBot 的 QQ/微信等群聊场景：

以 subprocess 进程隔离方式调用 brain.py，灵枢崩溃不影响 AstrBot 主进程；
自动携带通道三元组（群 id + 用户 id），群记忆隔离与隐私保护开箱即用；
支持以 AstrBot 指令直接触发 remember / recall / startup 等命令。

安装：把 scripts/astrbot_plugin_lingshu/ 整个目录放进 AstrBot 的插件目录，重载插件即可；配置里指定 Python 路径与灵枢技能目录（含 scripts/brain.py）。

可靠性设计

跨进程写锁：并发写入用独占锁互斥，不丢更新
损坏行自愈：JSONL 里出现坏行自动分拣——好行写回，坏行挪到 .corrupt，绝不静默丢失
备份/恢复：backup 打包整个记忆库（含 verbatim/ 与 skills/），自动修剪旧备份；restore 恢复前先留现状备份，校验 zip 合法性并防 zip-slip 路径穿越
只读降级：沙箱写盘被拒时自动降级为只读注入，已有的记忆照样带回；--home 支持把数据目录迁到工作区
原子写入：所有文件写入走临时文件 + os.replace，不会出现写一半的脏文件
运行日志可见：锁冲突、内部异常、解析报错写进 lingshu.log（滚动截断），面板「日志」页按级别查看——出问题先看这里，不用翻文件

常见问题：写操作报「文件被占用，请稍后重试」

现象：面板保存人格/配置等写操作偶发 400 错误。
原因：Windows 上某个进程短暂持有记忆库文件（~/.brain-memory/*.json）的读句柄（常见：杀毒软件实时扫描、系统索引器），原子替换需要等它松手。
排查：① 看面板「日志」页有没有对应异常记录（v2.29 起写失败必落日志，含路由与异常详情）；② 高频复现可用 Sysinternals 的 handle.exe ~/.brain-memory 查谁占着句柄；③ 反复出现可把记忆库目录加入杀毒软件排除列表。
恢复：稍等几秒重试即可——写路径带约 10 秒的指数退避重试，瞬时占用通常会自愈；持续失败才说明句柄被长期持有，按上面②定位占用者。

常见问题：AI 工具的自动审批拦截灵枢命令（报 invalid character '*'）

现象：在 Trae 等 AI 编程工具里，AI 助手执行 python scripts/brain.py <任意子命令> 被自动审批系统拦截，报 Automatic approval review failed: invalid character '*'。用户手动在终端里跑同样的命令完全正常。
原因：这不是灵枢的问题。报错格式（looking for beginning of value）来自审批服务自身的 JSON 解析器（Go 风格），即审批系统在审查这个动作时自己内部崩溃了，与命令内容、路径中文、脚本名均无关（已用对照实验验证：空脚本、只读命令能过，凡真正执行灵枢引擎的命令都被拦）。灵枢是纯 Python 标准库，命令与文档里的 * 只是 Markdown 加粗语法。
怎么办：
1. 让用户手动跑：AI 把要执行的命令原样列给用户，用户在自己的终端（PowerShell / CMD）里执行，把输出贴回来即可；
2. 走可视化面板：python scripts/brain.py panel 后在浏览器里操作——做梦、记忆增删、复核全部有界面按钮，完全不经过审批系统；
3. 重启 AI 工具重试：审批故障通常是会话级/临时性的，换个会话或重启客户端后可能恢复；
4. 不要让 AI 绕过：改名脚本、拆字符串拼命令等手段既不可靠也违反工具安全策略。

脚本 vs 模型：谁在真正干活

先打消一个误会：装上灵枢不等于自动拥有类人脑智能。 这套脚本是「存储、调度、数学计算」；真正的「智能」——合并记忆、理解情绪、提炼知识——仍然靠你接入的大模型。谁干什么，边界如下：

工作	谁干	说明
存储 / 衰减 / 强化 / 分层搬运	脚本	艾宾浩斯曲线、蔡格尼克、峰终、杏仁核劫持上限等全是公式，模型只负责触发命令
模糊回忆	脚本	字符二元组 / 词元加权，不需要模型参与（也因此是字面匹配，不是向量语义检索）
上下文注入包（startup 输出）	脚本	纯拼装，模型照抄即可
重放 → 碎片分组（dream）	脚本	pending 分组是启发式完成
碎片合并成新记忆、判断要不要	模型	这一段是幻觉高发区：合并错误、编造就发生在这里
情绪事件的解读（emotion evaluate）	模型	小模型会把中性对话判成愤怒/狂喜，或看不出反话
提炼知识库（knowledge tidy）	模型	小模型容易编造结论，直接沉淀成知识 = 幻觉落盘
技能自检（skill check）	模型	全靠模型读正文挑毛病

所以：脚本保证"记下来了、想得起来、删得掉、片段不丢"；模型决定"记得准不准、合并对不对、情绪认不认"。 想提高"记得准"，就换更强的模型或动 config。

模型适配与档位

灵枢不在脚本里硬堵模型能力，而是提供一个档位开关，让高风险自动能力按模型强弱开合：

能力	7B+ / 云端	1.5B–3B 小模型
记忆增删查（remember / recall / list）	✅ 完整	✅ 完整（脚本本身零模型依赖）
capture 原样封存	✅	✅
dream 重放分组	✅	✅（启发式部分可用）
dream --apply 合并结果	✅ 完整用	⚠️ 建议关：合并错误 = 幻觉记忆落盘
knowledge tidy	✅ 完整用	⚠️ 建议关（或强制走待审核）
emotion evaluate / mirror	✅	⚠️ 易判错情绪，改用手动 `emotion feel`
skill check	✅	⚠️ 结果可信度低

小模型模式（config set model_tier small）做的事：startup 注入包里追加「小模型模式」约束——不要自动 dream --apply、不要自动 knowledge tidy（产出须先 knowledge review 过目）、情绪评估改用手动 emotion feel。这只是注入提示，约束力取决于模型听话程度；3B 以下仍会漏执行，别指望它当保险丝。恢复：config unset model_tier（回到 auto）。

输出容错：所有需要模型产 JSON 的入口（dream --apply、knowledge tidy --apply）都做了容错解析——先按标准 JSON 读，失败再去掉 ```json 代码围栏，再失败截取第一个配平的 {...}，实在读不出来会明确报错并返回退出码 2，不再静默吞掉。解析失败时报错里带文件路径与内容开头，方便直接排查。

接入大模型（Ollama 示例）

灵枢是命令行工具，接入哪家模型由你决定，它只负责被调用。以本地 Ollama + qwen2.5 7b 为例：

# 1) 你家 Agent 是一次会话的调度者，为每次会话先跑三条
python scripts/brain.py startup --query "$USER_MSG"        # 把记忆注入提示前面
python scripts/brain.py remember "$USER_MSG" --source user # 用户说的入模记忆
# 2) 之后正常对话；水位到了再触发整理
python scripts/brain.py check-context --used 68            # 60 清点 / 75 做梦 / 90 封存
python scripts/brain.py dream --auto

Ollama 侧只需要一份 Modelfile，把"调用脚本"写进 system prompt 让它自己看情况执行：

FROM qwen2.5:7b
SYSTEM """你运行在本地，有记忆系统「灵枢」。每轮先按需执行：
- 新会话第一轮：运行 startup --query "本轮主题"，把输出原样作为你的记忆前缀。
- 用户说了值得记的事：运行 remember "<原话>" --kind fact|preference|emotion --importance 1-10。
- 需要回忆：运行 recall "<关键词>"。
- 上下文快满：运行 check-context --used <已用百分比>，并按提示配合。
如果命令没有可执行环境，就按 SKILL.md 的规则口头执行，绝不乱编记忆。
"""

更省事的替代：直接把这套框架装成 Agent 技能（skill install 全局化后，DSH / 本地 Agent 每会话自动读到 SKILL.md，按里面的机制走）。

规模上限与归档

记忆以 JSONL 纯文本存储（hippocampus/cortex/dust 等），没有数据库索引：

recall 模糊匹配要遍历全部记录，条数上万后每次命中会变慢（本地为毫秒级→百毫秒级，仍在可用区间）。
dream 会自动把一批短期记忆打包喂给模型，短期记忆越多，当次 token 消耗越大。

建议的养生方案：每周一次 backup（默认保留最近 20 份，自动修剪）；沉眠记忆交给冷热自动归档（每次做梦顺带雪藏进 archive 层，或 archive run 手工触发），不用再手动逐条删除——需要时 archive search / archive restore 找回；知识库定期 knowledge review 确认。真到数据膨胀影响手感的层级，把 --home 指向新目录再 restore 最近备份，旧目录留档。

技能名为什么是 lingshu

SKILL.md 的 frontmatter 是 name: lingshu（中文名放在 title: 灵枢）。原因是 DSH 的文件系统技能发现只认 kebab-case 名字，中文 name 会被静默跳过——表现就是"装了却看不到 / 像被改名"。

安装时用中文名或英文名都行：skill install 灵枢 --from <本目录> --yes 与 skill install lingshu ... 等价，目录与 frontmatter 统一落成 lingshu；安装目标自动选 DSH 的 ~/.dsh/skills（没有就回落 Trae 的 ~/.trae-cn/skills）。
装完想确认有没有被认出来：python scripts/brain.py skill list --global，正常显示 ✓；若是旧版中文目录会标 ✗ 目录名/name 不是 kebab-case，DSH 会跳过，跑一次 skill uninstall lingshu（会连旧目录一起删）再装即可。
手动拷进 DSH 技能目录时，目录名和 frontmatter name 都要用 kebab-case（lingshu / lingshu-lite / lingshu-tiny），路径是 ~/.dsh/skills/lingshu/。

如何更新灵枢

发布新版本的标准流程（维护者）

# 1. 改完代码后：生成/刷新发布清单（内置 version 与 SKILL.md 一致性校验）
python scripts/make_manifest.py
# 2. 升 SKILL.md 的 version，并在 CHANGELOG.md 写好对应小节（如 "## v2.33 — 标题"）
#    ——这两步由 pre-commit 钩子强制：代码变更不升版本、升版本没写 CHANGELOG 都会被拒绝
# 3. 提交并打 tag
git add -A && git commit -m "v2.33 …" && git tag v2.33 && git push --tags

用户侧更新

主仓库：https://gitee.com/htmcwy_0/lingshu-skill　镜像：https://github.com/266767398/lingshu-skill

对 AI 说一句「更新灵枢技能」即可，它会按 SKILL.md 的「更新灵枢技能」流程执行。手动更新也简单：

DIR="$HOME/.cache/灵枢-skill"
if [ -d "$DIR/.git" ]; then git -C "$DIR" pull; else git clone --depth 1 https://gitee.com/htmcwy_0/lingshu-skill.git "$DIR"; fi
# 然后把这些覆盖到技能目录：SKILL.md SKILL-lite.md SKILL-tiny.md README.md CHANGELOG.md docs/ assets/ scripts/ start-panel.bat

更新只替换技能本体文件；记忆数据在 ~/.brain-memory/，不会动。
具体保留下来的（都在数据目录，不在技能目录）：人格 persona.json（含初识与演化历史）、记忆 hippocampus.jsonl / cortex.jsonl / 归档、知识库与笔记、情绪与欲望状态、记忆关联 assoc.jsonl、梦报告 dreams/、运行日志 lingshu.log、你自己写的技能 skills/、扩展模块 extensions/、长期规则 lingshu.user.md、config.json。
更新前想更稳：python scripts/brain.py backup（产物在 ~/brain-backups/，自动保留最近 20 份）；更新后 python scripts/brain.py stats 对一眼条数与人格即可。

更新不会自动改名、也不会自动换目录：更新只覆盖技能仓库里的文件，而宿主扫的是全局副本目录——DSH 读 ~/.dsh/skills/，Trae 读 ~/.trae-cn/skills/。从 v2.11.2 之前装过的，旧的中文目录 灵枢/ 还在，会被 DSH 跳过。请重装一次：

python scripts/brain.py skill uninstall lingshu   # 会连旧的 灵枢/ 目录一起删（两个全局目录都清）
python scripts/brain.py skill install lingshu --from <本目录> --yes   # 自动装到 DSH 的 ~/.dsh/skills
python scripts/brain.py skill list --global       # 看到 ✓ 就对了

你长期手动维护的规则（DSH 只读保护、全局目录指回等）写进 ~/.brain-memory/lingshu.user.md（user-rules add <规则>），更新永不覆盖、每会话自动注入；全局 AGENTS.md 里  之外的自己写内容，更新时也原样保留。
更新前可对照 CHANGELOG.md 看这次改了什么；更新后跑一次 python scripts/brain.py stats 自检。
没有 git 的机器：到仓库页面下载 ZIP，解压后手动覆盖同名文件即可。

快速开始

# 初始化记忆库
python scripts/brain.py init

# 写一条记忆
python scripts/brain.py remember "用户喜欢用 Python 写脚本" --kind preference --importance 8

# 会话开始注入记忆（返回码 0=正常 10=只读降级 2=未初始化 64=命令写错）
python scripts/brain.py startup --query "本次会话主题"

# 回忆
python scripts/brain.py recall "Python"

# 记一次心情，看此刻心情
python scripts/brain.py emotion feel 开心 --intensity 0.8 --about "搞定了 bug"
python scripts/brain.py emotion now

# 上下文 75% 了，做梦整理
python scripts/brain.py dream --auto

# 上下文 90% 了，先封存保命
python scripts/brain.py capture "把这一段原文粘进来" --tag 逃生

# 启动可视化面板
python scripts/brain.py serve   # 或直接双击 start-panel.bat

命令速查

领域	命令
记忆	`remember` / `recall` / `inject` / `startup` / `list` / `forget`
上下文水位	`check-context --used 68`（60 清点 / 75 做梦 / 90 封存）
原样封存	`capture "<原文>" [--tag 逃生]`
做梦	`dream` / `dream --apply apply.json` / `dream --auto`
冷热归档	`archive show\|search <词>\|restore <id>\|run [--dry-run]\|count`（沉眠记忆自动雪藏，原文保留可回捞）
人格	`persona show\|set traits.幽默=70\|sync\|path\|interview\|self\|lock\|unlock\|history [--limit]\|rollback <序号>\|snapshot [--label]\|snapshots\|restore <名字>\|drift [--days 7] [--json]`
情绪	`emotion now\|arc\|list\|feel\|evaluate\|mirror\|desire\|config\|events\|adjust <序号>\|del <序号>\|cool\|check "回复文本"`
工作记忆	`work status\|add\|list\|done <序号>\|flush [--skip-done]\|clear`
会话模式	`mode show\|work\|human\|auto\|explain "一句话话题"`（工程会话自动隔离情绪；explain 看 auto 判定依据）
记忆关联	`assoc link <idA> <idB> --relation 因果 --why "..."\|unlink <idA> <idB>\|of <id>\|auto [--dry-run]\|graph --limit 300`
运行日志	`logs [--limit 20] [--level warn\|error] [--all]`（锁冲突/异常/解析报错，面板「日志」页同款）
审核闸	`review [--json]` / `review confirm <id>` / `review discard <id>`（记忆 m_* 与知识 k_* 通用）
用户规则	`user-rules show\|add <规则>\|clear`（写在数据目录 lingshu.user.md，更新永不覆盖，每会话自动注入）
自查	`audit [--json]`（待审计数 + 冲突记忆 + 该做什么）
知识库	`knowledge add\|list\|search\|show\|pin\|rm\|tidy\|review\|confirm <id>\|discard <id>`
冲突检查	`detect-conflicts [--json] [--limit 50]`（启发式，只提醒不下结论）
模型档位	`config show` / `config set model_tier small` / `config unset model_tier`
更新源认证	`config set gitee_token <令牌>` / `config set github_token <PAT>`（可选；Gitee 令牌在 gitee.com 设置-私人令牌生成，无需勾权限即可访问公开仓库；GitHub PAT 同理）
笔记	`note write\|search\|digest`
技能	`skill new\|edit\|list\|show\|check\|install\|uninstall\|rm\|find\|use\|borrow`
扩展模块	`ext new\|edit\|show\|list\|run\|check\|rm`（可执行钩子，数据目录，更新永不覆盖）
DSH 插件（只读）	`skill plugins [--json]`
成长	`growth status` / `growth review --days 7`
进化日志	`evolve log "标题" --kind persona\|skill\|knowledge\|thinking\|self`
备份恢复	`backup [--out 目录] [--keep 20]` / `restore <zip> [--yes]`
数据目录	`home show\|move\|verify`
与 DSH 同步	`sync dsh [--dir 目录] [--days 1] [--force]`
统计 / 面板	`stats` / `serve [--port] [--no-browser]`
通道三元组	`channel remember "内容" --group <id>\|recall "词" --group <id>\|user <id>`（群隔离/跨群记忆/按人回忆）
群友隐私	`channel privacy status\|grant <用户>\|revoke <用户>`（本人授权门控，未授权查第三人返回退出码 4）

全局参数：--home <目录>（切换数据目录）、--ro（只读降级）。

项目结构

灵枢-skill/
├── SKILL.md                # 技能本体：AI 每会话必读的主文件（动作+高频命令+docs 索引）
├── SKILL-lite.md           # 精简版：小模型 / 新人用的降档说明书
├── SKILL-tiny.md           # 最小试用版：只剩记忆三件套的入门说明
├── docs/
│   ├── mechanics.md        # 机制详解（做梦/情绪/知识库/技能/人格规则…）按需 Read
│   ├── commands.md         # 完整命令速查 + 可视化面板 + 故障排查 FAQ
│   └── models.md           # 模型分级降档 + 幻觉防护三道闸 + 如何更新灵枢
├── CHANGELOG.md            # 变更历史
├── start-panel.bat         # 一键启动可视化面板
├── cordis-plugin/          # DSH/Cordis 插件（一个插件一个子目录）
│   └── lingshu-startup/    # 会话启动自动跑 startup 并注入上下文
├── assets/
│   └── panel.html          # 可视化面板前端（单文件，无依赖）
└── scripts/
    ├── brain.py            # 入口与 re-export（保持全部旧命令/旧 import 兼容）
    ├── core.py             # 环境/配置/路径/锁/原子写/JSONL IO/只读降级
    ├── memory.py           # 分层记忆/回忆/归档/工作记忆/capture/关联/注入与统计
    ├── emotion.py          # 七情六欲/心境/认知评价/共情/理智
    ├── persona.py          # 人格/快照回滚/初识与自我设定
    ├── dream.py            # 做梦：聚类巩固与梦境应用
    ├── cli.py              # 子命令解析与执行/备份恢复/启动注入/每日例行
    ├── growth.py           # 成长系统：知识库/笔记/技能/进化日志/DSH 插件扫描
    ├── panel_server.py     # 本地面板 HTTP 服务（token 鉴权 + 来源校验）
    ├── astrbot_plugin_lingshu/  # AstrBot 插件（subprocess 进程隔离，通道三元组开箱即用）
    └── check_version.py    # 版本硬检查：改代码必须升 SKILL.md 版本（可装 pre-commit）

运行时数据（默认 ~/.brain-memory/，--home 可迁移）：

.brain-memory/
├── hippocampus.jsonl       # 短期记忆（海马体）
├── cortex.jsonl            # 长期记忆（皮层）
├── dust.jsonl              # 淡忘区
├── archive.jsonl           # 归档层（冷热自动归档的沉眠记忆，原文保留）
├── working.jsonl           # 工作记忆（会话暂存）
├── emotions.jsonl          # 情绪事件流（心情按半衰期从这里叠加出来）
├── emotion_checks.jsonl    # 情绪-输出一致性告警记录（滚动保留 200 条）
├── desires.json            # 六欲状态（生、耳目口鼻感官欲等底层需要）
├── assoc.jsonl             # 记忆关联边（联想图谱）
├── persona.json            # 人格档案
├── persona_snapshots/      # 人格快照（snapshot / restore / drift 基准）
├── config.json             # 配置（阈值/权重）
├── dream_state.json        # 做梦状态（上次做梦时间等）
├── daily_state.json        # 每日例行状态
├── knowledge.jsonl         # 知识库
├── knowledge/              # 知识库附件（index.json）
├── notes.jsonl             # 日记/日志/成长复盘
├── evolution.jsonl         # 进化日志
├── skills.json             # 技能注册表
├── skills/                 # 自己写的技能
├── extensions/             # 扩展模块（可执行钩子 inject/run，更新永不覆盖）
├── lingshu.user.md         # 用户附加规则（更新永不覆盖，每会话自动注入）
├── lingshu.log             # 运行日志（锁冲突/异常/解析报错，面板「日志」页可看）
├── consent.json            # 群友隐私授权记录（channel privacy grant/revoke，v2.35）
├── panels/                 # 自定义面板（热加载切换，损坏自动回退默认面板）
├── panel-market/           # 本机面板共享市场（拷目录即流通）
├── dreams/                 # 梦报告与 pending（apply 草稿 apply_draft.json 也在这）
├── verbatim/               # capture 原样封存的保险柜
└── backups/                # 备份

边界

灵枢管人格/情绪/关系，DSH 管工作/项目——每日用 sync dsh 把灵枢日志摘要自动进 DSH 当日日志，两边各记各的，不重复、不漂移。

纯本地、零依赖、你的数据永远是你的。隐私是默认，不是选项。

Install

README