qing-self
v0.4.0
Published
Scaffold for layered agent memory: memory files, judgment cards, full/compact model handoff, two-question ruler, compression review, portability diff, three-factor recall and schema check. Format-locked, zero-dependency, JSON-first.
Maintainers
Readme
qing-self · 半个体化脚手架
给 DSH 上的 agent / 角色一键装上分层记忆+判断卡+转生交接+压缩审查+迁移差异验证的结构。 只给格式和流程,不给内容:没有别人的真实判断、没有私人记忆、没有任何暗桩。
已改名:
dsh-self→dsh-memory-scaffold(v0.2.0)→qing-self(v0.3.0)。CLI 二进制仍是dsh-self;斜杠命令、Agent 工具、.dsh-self/路径与 format schema 都不变。
- 零依赖、不联网、不调用 LLM、不做向量检索
- 全部是纯 markdown / JSON,任何编辑器可读、可 diff、可迁移
- 8 个命令全部支持
--json,文件格式公开锁定 —— 其他插件可以直接读、可以直接接 - 模板版本化(
template=v1.0.0+CHANGELOG),升级不覆盖用户文件
30 秒装好
dsh plugin --profile web add git+https://github.com/malabananclauss-rgb/qing-self#v0.3.0看到重启提示就重启,然后在工作区跑 /self-init。
它是什么: 给 DSH agent 一套跨模型/跨会话续命的结构——分层记忆文件、判断卡、完整接续包(8 个验证问题)+6–10 KB 紧凑版、以及判断“可迁移/可接续”的两问尺子。只是结构脚手架,不是记忆引擎:不自动捕获对话、不做嵌入/召回、不调用模型。

为什么需要它
DSH 上已经有大量记忆类插件(存储、检索、右侧栏 UI、自动捕获……),但多数用户卡在同一个问题:
「我知道要让 AI 有记忆连续性,但不知道该建哪些文件、每个文件放什么、什么时候写、什么时候压、换模型时交什么。」
这个包卖的不是记忆内容,是记忆的骨架和流程:四个文件、八个动作,照着做就能从"每次重新解释自己"变成"分层记忆+可验证交接"。
它给什么
| 命令 | 作用 |
| --- | --- |
| init | 在工作区建四层结构:hot/state.md(状态)、index.md(索引)、judgments.md(判断库)、judgments-cards.md(判断卡),外加 decisions.md(本次会话决策)+模板+QUICKSTART.md。幂等:只补缺失文件,从不覆盖已写内容。 |
| judge | 新增一条判断卡:结论/为什么/失败反例/未完成/来源;自动编号(J001…),同时写入 judgments 与 cards 两张表。 |
| handoff | 读你的记忆,生成「接续包」文档+ 8 个验证问题,并写一份同名 .json 侧车文件给其他插件读。换模型/换会话前跑。--compact 出 6–10 KB 紧凑版(方向+hot+活判断精简+按 --focus 选卡+未完成+验证问题);--focus 按主题挑判断卡。 |
| review | 压缩审查:hot 大小(>800 字 / 2KB 告警)、上下文占比提示、待落盘项清单、判断库/卡一致性、失效索引指针、模板版本漂移。 |
| ruler | 独特两问:把一条判断变成两条针对性的具体追问(① 换一个版本的我来用还成立吗=可迁移性 ② 明天全忘后还能被捡回来吗=可接续性)+可直接复制的提示词+最大风险点。本地模板+关键词启发式,零模型调用、不联网、不写文件。 |
| diff | 迁移差异验证(A→B):比较两份评分 JSON({"total":…,"items":[{name,score,weight}]}),输出总分差/总分差异率、逐项差异率(|b−a|/weight×100)、差异集中点与方向。方向不对称,互换 A/B 再跑一次。只读。 |
| recall | 三要素检索:从 judgments.md 按 relevance(查询词命中结论+边界)、recency(hits.jsonl 最近时间/次数)、importance(状态+卡是否存在)打分排序,输出 top N 与三要素分数。只读,零模型调用。 |
| check | schema 校验:固定 7 列、状态枚举(中英文 canonical 均可)、常用/本能必须有卡、J616+ 新行必须是指针格式;输出违规数与行号,有违规退出码 1。只读。 |
独特两问:可迁移性 × 可接续性(零模型调用)
把一条想法变成可继承的判断之前,先跑 ruler。它把你的原话变成两条具体追问,
而不是复读别人也说过的话:
- 可迁移性:这条判断,换一个版本的我来用,还成立吗?它依赖哪些资源/时间/环境/模型条件? 只对“当时的我”成立的,不是判断,是处境。
- 可接续性:如果明天我全忘了,这条判断还能被捡回来吗?是能被写下来、被别人或下一版捡回, 还是只靠“我记得”?靠记忆的,会随身体一起消失。
dsh-self ruler --situation "我该不该把发布交给青决定?" --context "本周内要给答复。"
dsh-self ruler 我该不该换模型 # 直接写在命令后也可输出还包含一行「最大风险点」和一段可直接复制的提示词(粘到任何 AI,或自己逐问回答)。
DSH 里用 /self-ruler 或 dsh_self_ruler 工具,用法相同。不调用模型、不联网、不写任何文件——判断仍然是你的。
适用:不可逆决定、带代价的承诺、评价别人、花钱、要求别人承担后果。
它不是什么(诚实边界)
- 不是存储/检索插件:不自动捕获对话、不做向量搜索、不注入 prompt、不改你的上下文。
- 不是内容包:模板只有占位示例;真实身份、判断、关系史都得你自己写。
- 不是运行时:只是一个确定性的文件脚手架+检查器;换掉 DSH 也能用(纯 Node CLI)。
卖点与壁垒(生态视角)
- 格式锁定(软锁定):目录结构、表头列名与列序、状态枚举、卡字段名、机器标记全部写进
docs/FORMAT.md。第三方插件想兼容就只能按这个格式读写——这形成事实标准,但不加密、不做暗桩、不写排他逻辑:用户随时可以搬走、手改、迁移。 - 版本化模板:每个模板带
template=v1.0.0 format=1标记,manifest.templateVersion记录安装版本,CHANGELOG.md+ GitHub Release 作为迭代与迁移通道。升级不覆盖用户文件,靠review提示+手动合并,避免"升级毁记忆"。 - 生态钩子(我们当 hub):8 个命令的
--json信封、handoff 的 JSON 侧车、可导入的格式解析器 (qing-self/format)+docs/ECOSYSTEM.md。别的插件(会话启动提示、压缩闸门、交接消费者、面板、看板)可以只读地接上来,而不需要复制我们的实现。 - 不给内容:只给结构和流程模板。对用户诚实(红线:不欺骗),也让它能和任何记忆存储插件叠加而不是冲突——存储归别人,判断层归这里。
安装
方式 A — 从仓库安装(推荐,含斜杠命令+Agent 工具)
dsh plugin --profile web add git+https://github.com/malabananclauss-rgb/qing-self#v0.3.0
# 或用 v0.3.0 Release 里的预构建 tarball:
dsh plugin --profile web add https://github.com/malabananclauss-rgb/qing-self/releases/download/v0.3.0/qing-self-0.3.0.tgz
# 或先 clone 再指向目录:
# git clone https://github.com/malabananclauss-rgb/qing-self
# dsh plugin --profile <你的 profile> add ./dsh-self
# 或在 DSH Web 的插件页 / plugin_manager 用 install_bundle 安装本地目录安装/启用是用户自己的权限操作;本仓库只提供可安装包,不会替你改 profile。
方式 B — 只用 CLI(不装插件也能用)
node bin/dsh-self.mjs init方式 C — npm:还没发布;请用上面的 GitHub 安装。
快速开始
# 1. 在工作区初始化
node bin/dsh-self.mjs init --json
# 2. 读 memory/QUICKSTART.md,把 memory/hot/state.md 里的 [占位] 换成你自己的
# (身份锚 / 判断核 / 红线 / 当前任务 / 卡点 / 下一步)
# 3. 记录第一条判断
node bin/dsh-self.mjs judge \
--conclusion "先跑通最小版本再迭代" \
--why "没跑过的代码等于没写" \
--failure "一次性脚本可以例外" \
--unfinished "最小版本的边界还没定" \
--source "docs/设计稿.md#L12" \
--status common
# 4. 换模型 / 换会话前
node bin/dsh-self.mjs handoff --json
node bin/dsh-self.mjs handoff --compact --focus "磨镜,好名"
# 5. 重大决定前:三个具体追问,零模型调用
dsh-self ruler --situation "我该不该接这个任务?谁承担代价?"
# 6. 每周或压缩前
node bin/dsh-self.mjs review
# 7. 迁移验证:两份评分 JSON 双向对比
node bin/dsh-self.mjs diff --a score-a.json --b score-b.json
# 8. 按任务检索最相关判断
node bin/dsh-self.mjs recall --task "怎么验证迁移" --top 5
# 9. 校验判断库 schema(有违规退出码 1)
node bin/dsh-self.mjs check --json命令参考
dsh-self <init|judge|handoff|review|ruler|diff|recall|check> [options]通用:-w/--workspace <dir>(默认当前目录)、--dir <name>(记忆目录,默认 memory)、
--json、-h/--help、--version。
| 命令 | 选项 |
| --- | --- |
| init | --lang zh\|en |
| judge | --conclusion --why --failure --unfinished --source(必填);--boundary --scene --status candidate\|common\|instinct\|refuted\|archived(可选) |
| handoff | --out <file.md>(可选;默认 memory/handoffs/handoff-<时间戳>.md);--compact 紧凑版(目标 6–10 KB);--focus 主题1,主题2 按卡标题→结论→正文匹配,每主题最多 2 张卡,只能配 --compact |
| review | --context-budget <字符数>、--fail-on-warn(CI 用,有可操作告警时退出码 1) |
| ruler | --situation <处境/决策>(也可直接跟一句话)、--context <补充背景>、--lang zh\|en |
| diff | 必填 --a <A.json>、--b <B.json> |
| recall | --task <描述>(也可直接跟一句话)、--top 5(默认 5,最多 100) |
| check | 无参数(读记忆目录) |
退出码:0 成功;1 review --fail-on-warn 或 check 有违规;2 用法错误;3 运行/格式错误。
完整 JSON 契约见 docs/ECOSYSTEM.md。
DSH 集成
装上插件后:
- 斜杠命令:
/self-init、/self-judge、/self-handoff、/self-review、/self-ruler、/self-diff、/self-recall、/self-check(参数同 CLI,去掉--workspace/--dir,用当前 agent 的工作区) - Agent 工具:
dsh_self_init、dsh_self_judge、dsh_self_handoff、dsh_self_review、dsh_self_ruler、dsh_self_diff、dsh_self_recall、dsh_self_check - 工具会占一点提示词空间(8 个 schema)。只想用斜杠命令的话,在行 config 里设
tools: false。
行配置(cordis.patch.yml 的 config,可被用户 patch 覆盖):
| 键 | 默认 | 含义 |
| --- | --- | --- |
| memoryDir | memory | 记忆目录(相对工作区,或绝对路径) |
| hotMaxChars / hotMaxBytes | 800 / 2048 | hot 告警阈值 |
| contextBudgetChars | 32000 | 上下文占比估算预算 |
| contextShareNoticePercent / contextShareWarnPercent | 3 / 10 | 占比提示/告警阈值 |
| commands / tools | true / true | 是否注册斜杠命令 / Agent 工具 |
生态钩子(给其他插件)
--json信封:ok / command / formatVersion / templateVersion / latestTemplateVersion / toolVersion / workspace / memoryRoot / generatedAt / data / warnings / errorshandoff生成.md+.json侧车(schema: "dsh-self/handoff"),新模型接续、看板、压缩闸门都可复用- Node 消费方可
import { parseJudgmentsTable, parseCards, hotStats } from 'qing-self/format' - 只剩文件也能接:按
docs/FORMAT.md的锁定格式读 markdown - 典型接法(会话启动提示、压缩闸门、交接消费者、面板/看板)见
docs/ECOSYSTEM.md§6
格式锁定(format v1)
memory/
├── hot/state.md
├── index.md
├── judgments.md
├── judgments-cards.md
├── decisions.md
├── QUICKSTART.md
├── handoffs/handoff-<ts>.md + .json
└── .dsh-self/manifest.jsonjudgments 表锁死 7 列:id | conclusion | boundary | source | status | card | updated;
状态枚举锁死 5 值;卡字段锁死 why/failure/unfinished/source(+可选 scene)。
完整契约(含字符数定义、转义、标记、manifest 字段、兼容规则)见 docs/FORMAT.md(中文版:FORMAT.zh-CN.md)。
对已有老库的读取容忍: 5 列中文判断表、中文状态别名(候选/常用/本能…)、
中文卡字段(- **为什么**:…)、多指针 index(; 分隔)、缺 manifest 都可读
(见 docs/FORMAT.md §11);往 5 列旧表写入会被明确拒绝(LEGACY_FORMAT_READ_ONLY+升级提示)。
版本化模板与更新
- 模板目录
templates/v1/{zh,en}/,每个文件带<!-- dsh-self template=v1.0.0 format=1 --> init把templateVersion写进memory/.dsh-self/manifest.json- 升级包后跑
review:若模板版本不同会提示TEMPLATE_UPGRADE_AVAILABLE,按CHANGELOG.md手动合并;工具不会覆盖用户已经写的内容 - 发布节奏:GitHub Release(
v<packageVersion>),CHANGELOG 记录包版本、模板版本、格式版本三条线
隐私与安全
- 记忆是未加密的纯文本,本地任何进程都能读;不要写密码/令牌/证件号,只写"在哪找"
- 本包不联网、不上传、无遥测;
--json只写到 stdout 和本地文件 - 记忆目录是否提交 git 由用户决定;建议先看清楚再
git add
已知限制
- 不自动注入上下文(这是别的插件的活,本包只提供结构)
- 上下文占比是按字符预算的估算,不是平台实测值(可用
--context-budget校准) - 假设单写者:同一记忆目录不要被多个进程并发写
- 模板升级靠手动合并(不自动重写,避免毁数据)
- 只有 format v1,暂无跨版本迁移器(升级会明确报
UNSUPPORTED_FORMAT而不是猜) - 未发布到 npm / 插件市场(当前交付形态:本地目录安装);GUI 面板按产品定义不做
目录结构
index.js Cordis Host 插件入口(挂斜杠命令+Agent 工具)
cordis.patch.yml DSH bundle patch
lib/ core / format / cli / plugin / fsx / version
bin/dsh-self.mjs CLI 入口
templates/v1/{zh,en}/ 版本化模板
docs/FORMAT*.md 格式锁定契约(中英)
docs/ECOSYSTEM.md --json 与生态对接契约
examples/consumer.mjs 只读消费示例
test/selftest.mjs 自测(59 项)
SELFTEST.md 自测记录开发与自测
node test/selftest.mjs # 59/59;会创建 test/.tmp 并在结束时清理
SI_KEEP_TMP=1 node test/selftest.mjs # 保留测试目录排查License
MIT。见 LICENSE。
