clearai-dsh 0.2.0 → 0.2.1

package/lib/host.js

@@ -18,7 +18,7 @@
 import { readdirSync, statSync } from 'node:fs'
 import { join, relative, resolve, sep } from 'node:path'
 import { z } from 'zod'
-import { HUMAN_GATE_ACTIONS, HUMAN_GATE_MARK, MUTATION_KIND, STATE_VERSION, applyEvent, applyMutations, derive, emptyState, renderCard, view } from './fold.js'
+import { HUMAN_GATE_ACTIONS, HUMAN_GATE_MARK, MUTATION_KIND, STATE_VERSION, applyEvent, applyMutations, derive, emptyState, inspectGraphSelection, renderCard, view } from './fold.js'
 import { describeDomainShelf, formatAssertion, validateAssertions, validatePredicate, validateTerm } from './domain-language.js'
 import { install as installInvariants } from './invariant.js'
 
@@ -655,6 +655,36 @@ export function apply(ctx) {
 			return reply(200, { ok: true, complete: true, entries })
 		})
 
+		/**
+		 * `GET /api/clearai/inspector?sessionId=…&kind=…&id=…`
+		 *
+		 * **知识 Inspector**:图上点了一个节点或边,把它的定义 / 关系 / 断言 / 证据链 / 历史取回来。
+		 *
+		 * 为什么走路由而不是塞进 `view()`:选择是**动态**的——把每个节点每条边的完整链都预先
+		 * 推进投影,等于对一张 61 节点 / 147 边的图各算一遍,而人一次只看一个。
+		 * 组装仍然只有一处实现(`inspectGraphSelection`,纯函数在宿主半),所以
+		 * 「客户端自己拼证据链」这条口子没有开。
+		 *
+		 * 只读:**不产生任何变更**,也拿不到写入口。
+		 */
+		route('/api/clearai/inspector', ['GET'], async (httpRequest) => {
+			const url = new URL(httpRequest.url)
+			const sessionId = url.searchParams.get('sessionId') ?? ''
+			const session = ctx.sessions.get(sessionId)
+			if (session === undefined) return reply(404, { ok: false, error: 'no_live_session' })
+			/**
+			 * 直接用本模块的折法读状态,不走 `ctx.get('clearai')`:那条门面是同一条 fiber 上
+			 * 提供给**预设侧**用的,而这条路由只是把同一个纯函数接到 HTTP 上——
+			 * 中间多一跳服务解析,只会多一种「服务没接上」的失败模式。
+			 */
+			const state = ctx.sessionProjections.stateOf(session, 'clearai')
+			if (state === null || state === undefined) return reply(200, { ok: true, found: false })
+			const found = inspectGraphSelection(state, { kind: url.searchParams.get('kind') ?? '', id: url.searchParams.get('id') ?? '' }, derive(state))
+			/** 找不到不是错误:那个对象可能刚被废止或本来就不在(如实说 `found: false`,不编一份空的)。 */
+			if (found === null) return reply(200, { ok: true, found: false })
+			return reply(200, { ok: true, found: true, inspector: found })
+		})
+
 	})
 
 	ctx.effect(
@@ -720,6 +750,16 @@ export function apply(ctx) {
 					/** 一条断言的一行人话(货架 / 卡片 / 查询共用同一句话,免得三处各写一套)。 */
 					format: (sessionId, assertion) => formatAssertion(stateOf(sessionId).lexicon, assertion),
 				},
+				/**
+				 * **知识 Inspector**:一个选择 → 它的定义 / 关系 / 断言 / 证据链 / 历史。
+				 *
+				 * 组装住在纯函数里(`inspectGraphSelection`),这里只把当前状态喂给它——
+				 * 客户端因此永远拿不到「自己拼链」的机会,凡是读到链的地方都同源。
+				 */
+				inspector: (sessionId, selection) => {
+					const state = stateOf(sessionId)
+					return inspectGraphSelection(state, selection, derive(state))
+				},
 			}),
 		'clearai: read facade',
 	)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clearai-dsh",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "ClearAI: The Epistemic Loop, native to DSH.",
   "type": "module",
   "private": false,
@@ -35,6 +35,10 @@
     "node": ">=22"
   },
   "dependencies": {
+    "@xyflow/react": "^12.11.6",
+    "docx": "^9.7.1",
+    "graphology": "^0.26.0",
+    "graphology-layout-forceatlas2": "^0.10.1",
     "zod": "^4.6.1"
   },
   "dsh": {
@@ -59,7 +63,7 @@
     "worldline"
   ],
   "scripts": {
-    "test": "bash test/run.sh",
+    "test": "node tools/build-vendor.mjs && bash test/run.sh",
     "build": "node tools/build-package.mjs",
     "verify": "node tools/verify-package.mjs",
     "verify:deploy": "node tools/verify-deploy.mjs",
@@ -67,6 +71,13 @@
     "pack": "node tools/build-package.mjs && npm pack ./dist/clearai-dsh",
     "release": "node tools/build-package.mjs && node tools/verify-package.mjs && node tools/verify-clean-install.mjs && npm pack ./dist/clearai-dsh --pack-destination dist",
     "e2e": "node tools/e2e-run.mjs",
-    "e2e:long": "node tools/e2e-parallel.mjs"
+    "e2e:long": "node tools/e2e-parallel.mjs",
+    "vendor": "node tools/build-vendor.mjs",
+    "check:browser": "node tools/browser-graph-check.mjs",
+    "shots": "node tools/graph-shots.mjs"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2",
+    "playwright-core": "^1.63.0"
   }
 }

package/presets/clearai/agent.cordis.yml

@@ -150,6 +150,13 @@
     # 只有一个猜想时,「验证」容易退化成找证据支持自己。修订目标不受此限。
     # 内核缺省是 0(=机制中立);**这里写 2 是产品立场**,所以它是硬门,不是文案。
     minHypotheses: 2
+    # 知识门:将要升格的命题必须已有断言的形态,否则结案被拒(在派评估者**之前**拦)。
+    # 为什么要有它:断言一直是「加法,不是门槛」,于是模型的最优策略就是
+    # 「检索 → 总结 → 写报告」——本体图、实体图、认识论三张图都长不出来,
+    # 因为**完成函数里没有它们**。让缺口进卡只解决「看得见」,这一道解决「绕不过」。
+    # 它与 minHypotheses 是两条不同的立场(开工要有候选对比 / 结论要有形态),所以是两个键。
+    # 内核缺省 false(= 断言始终是加法);这里写 true 是产品立场。
+    requireTypedPromotion: true
     # deny_rules 十条里可移植的九条(路径越狱那条不搬:宿主沙箱已经拥有它,ClearAI 自己也说「不重复」)
     bashDenyRules: true
     # 独立评估者:spawn = fresh context(fork 会继承历史,做的人与判的人就分不开了)

package/presets/clearai/plugins/clearai-kernel.js

@@ -461,6 +461,7 @@ export const CONFIG_KEYS = [
 	'templateDir',
 	'l4RejectSelfWritten',
 	'minHypotheses',
+	'requireTypedPromotion',
 	'bashDenyRules',
 	'auditProvider',
 	'auditTimeoutMs',
@@ -642,6 +643,14 @@ export function apply(ctx, config = {}) {
 		l4RejectSelfWritten: config.l4RejectSelfWritten !== false,
 		/** ClearAI 代码里「≥2 条假设」只是文案;默认不强制。 */
 		minHypotheses: config.minHypotheses ?? 0,
+		/**
+		 * **知识门**:将要升格的命题必须已有断言的形态,否则结案被拒。
+		 *
+		 * 与 `minHypotheses` 是**两条不同的立场**,所以是两个键,不是一个:
+		 * 前者说「开工要有候选对比」,这条说「结论要有形态」。一个部署完全可以只要前者。
+		 * 机制侧缺省关(= 断言始终是加法),preset 里写 true——与 `blockedThreshold` 同一个模式。
+		 */
+		requireTypedPromotion: config.requireTypedPromotion === true,
 		bashDenyRules: config.bashDenyRules !== false,
 		auditProvider: config.auditProvider ?? 'spawn',
 		auditTimeoutMs: config.auditTimeoutMs ?? 240000,
@@ -720,6 +729,24 @@ export function apply(ctx, config = {}) {
 		return process.cwd()
 	}
 
+	/**
+	 * 这个会话是不是**派出去的子会话**(评估者 / 侦察 / 执行者 / 横评仲裁)。
+	 *
+	 * 判据读宿主的会话头:`dsh-subagent` 生成子会话时写死 `parentSession`——与它写死
+	 * `cwd: parentHeader.cwd` 是同一处,所以「共享工作区」与「身份是子会话」总是一起出现。
+	 * 会话服务问不出来时按「不是子会话」处理:与 `sessionCwd` 的退路同一个方向,
+	 * 拿不到证据时维持既有行为,不新增一条静默分支。
+	 */
+	function isSpawnedChild(sessionId) {
+		try {
+			const header = ctx.get('sessions')?.get?.(sessionId)?.header
+			if (header === null || typeof header !== 'object') return false
+			return header.origin === 'subagent' || header.parentSession !== undefined
+		} catch {
+			return false
+		}
+	}
+
 	/**
 	 * 认一条假设:`id` 最稳,**原文**与**唯一前缀**(≥8 字)也认。
 	 *
@@ -2604,6 +2631,11 @@ export function apply(ctx, config = {}) {
 
 	/** 写货架;内容没变就返回 null(调用方据此决定要不要在卡里提一句)。 */
 	function ensureFactsShelf(sessionId, state) {
+		/**
+		 * 与词汇货架**同一条所有权规则,同一个位置**(写入口):子会话的投影里
+		 * 没有主线的事实,让它铺只会按它自己那份重写 `INDEX.md`。
+		 */
+		if (isSpawnedChild(sessionId)) return null
 		/**
 		 * 货架要显示「被推翻」那个读数,而它是**派生的**(fold 的 derive),不在原始状态里。
 		 * 所以这里问一次读面,而不是在货架里重算一遍(重算 = 第二份判据,必然漂)。
@@ -2631,8 +2663,23 @@ export function apply(ctx, config = {}) {
 	 *
 	 * 带 `mutations` 时按**这一步之后**的样子渲染:工具返回前货架就已更新,读的人不必等下一回合。
 	 */
+	/**
+	 * 铺领域词汇货架(幂等)。
+	 *
+	 * **写入口自带所有权判据:派出去的子会话结构上写不进这份文件。**
+	 *
+	 * 规则一句话:工作区级读面属于拥有账本的会话。子会话(评估者 / 侦察 / 执行者)与主线
+	 * 共享同一个工作区,却持有**另一份(空的)投影**——让它照自己的投影重铺,
+	 * `renderShelf(子会话)` 渲染出的就是「还没有词条」的占位版。真跑里评估者两次读到
+	 * 7 行占位版、主线连读三次都是 96 行 21 词条,两边各自稳定:文件在「谁最后铺了一拍」
+	 * 之间摆动,而两边谁都没说谎。子会话**读**这份货架(评估者核对判据正要读它),但不写。
+	 *
+	 * 判据放在**写函数里**而不是调用点,与 `tools/pre-execute` 拒模型写 `clear/` 是同一条
+	 * 纪律:边界住在咽喉点,新增多少调用点都绕不过(不可表达优于不可违反)。
+	 */
 	function ensureDomainShelf(hostService, sessionId, mutations = []) {
 		if (hostService?.domain?.renderShelf === undefined) return ''
+		if (isSpawnedChild(sessionId)) return ''
 		try {
 			const body = hostService.domain.renderShelf(sessionId, Array.isArray(mutations) ? mutations : [])
 			const file = join(sessionCwd(sessionId), 'clear', 'ontology', 'domain.md')
@@ -2834,6 +2881,35 @@ export function apply(ctx, config = {}) {
 			const goalId = isRevision ? state.goal.id : uniqueId('g')
 			const revision = isRevision ? state.goal.revision + 1 : 1
 			const promoteAtLevel = LEVELS.includes(args.promote_at_level) ? args.promote_at_level : 'L3'
+			/**
+			 * **修订不许给同一句话发新身份。**
+			 *
+			 * 真跑踩出来的:一轮长跑里目标改过一次版,卡上就出现 4 条主张的 6~8 行读数——
+			 * 同一句话挂着两个 id、各报一个状态(一个「已支持」、另一个「未触及」),
+			 * 模型得自己去调和两份自相矛盾的读数。而 id 是身份:主张原文没变就该用回原来的 id,
+			 * 这样「这条猜想被验到哪一级」跨版本仍然接着算。
+			 *
+			 * 反过来,**这一版没再列出来的**要如实落成 `hypothesis/superseded`:
+			 * 折法早就认识这条变更,只是从来没有人发过它(与 `retracted` 当年那个「声明了没有生产者」
+			 * 是同一种病)。不发它,被放弃的猜想会永远挂在 `proposed` 上,结案时又变成一条假的「没看过」。
+			 */
+			const existing = state.hypotheses.filter((item) => item.goal === goalId)
+			const claimKey = (text) => String(text ?? '').trim().replace(/\s+/g, ' ')
+			const idByClaim = new Map(existing.map((item) => [claimKey(item.claim), item.id]))
+			const reused = new Set()
+			const nextHypotheses = hypotheses.map((hypothesis, index) => {
+				const claim = hypothesis.claim.trim()
+				const carried = idByClaim.get(claimKey(claim))
+				if (carried !== undefined) reused.add(carried)
+				return {
+					id: carried ?? `h-${Math.random().toString(36).slice(2, 8)}`,
+					claim,
+					refute_when: hypothesis.refute_when.trim(),
+					/** 断言随假设落账;没写就是 null(加法,不是门槛)。 */
+					assertions: Array.isArray(hypothesis.assertions) ? hypothesis.assertions : null,
+					version: index + 1,
+				}
+			})
 			mutations.push({
 				t: 'goal/set',
 				id: goalId,
@@ -2842,15 +2918,14 @@ export function apply(ctx, config = {}) {
 				promote_at_level: promoteAtLevel,
 				revision,
 				reason: isRevision ? String(args.reason).trim() : null,
-				hypotheses: hypotheses.map((hypothesis, index) => ({
-					id: `h-${Math.random().toString(36).slice(2, 8)}`,
-					claim: hypothesis.claim.trim(),
-					refute_when: hypothesis.refute_when.trim(),
-					/** 断言随假设落账;没写就是 null(加法,不是门槛)。 */
-					assertions: Array.isArray(hypothesis.assertions) ? hypothesis.assertions : null,
-					version: index + 1,
-				})),
+				hypotheses: nextHypotheses,
 			})
+			for (const dropped of existing) {
+				if (reused.has(dropped.id)) continue
+				const promoted = (state.facts ?? []).some((fact) => fact.hypothesis === dropped.id)
+				if (promoted) continue
+				mutations.push({ t: 'hypothesis/superseded', goal: goalId, id: dropped.id, claim: dropped.claim, by: `rev${revision}` })
+			}
 			let scoutNote = ''
 			if (!isRevision && CFG.precommitRecon) {
 				// 立约前侦察:harness 发起(不是模型请求),一生一次,且只在真的有人给过材料时做
@@ -2945,6 +3020,43 @@ export function apply(ctx, config = {}) {
 				)
 			}
 			const derived = hostService.derive(sessionId)
+			/**
+			 * **知识门:核心结论不许以纯散文升格。**
+			 *
+			 * 位置有讲究——它坐在「计划已收尾」之后、**派评估者之前**。判据与准入同一条顺序纪律:
+			 * 先把能做的前提查完,再花钱请人裁决;等评估卡回来才发现没形态,那一次子 run 就白花了。
+			 *
+			 * 为什么需要它:断言一直是「加法,不是门槛」,于是真跑里模型的最优策略就是
+			 * 「检索 → 总结 → 写报告」——本体、实体、认识论三张图都长不出来,因为完成函数里没有它们。
+			 * 让缺口进卡(见 `renderCard`)只解决「看得见」;这一道解决「绕不过」。
+			 *
+			 * **判据是结构谓词,不是词面**:将要升格的命题里,只要有一条没有断言就拦。
+			 * 出口有两条,都是诚实的:补上断言的形态再结,或者如实 `abandoned`。
+			 * 缺口不许被伪装成 support(那是「造证」,比不结案坏得多)。
+			 *
+			 * 开关是 `requireTypedPromotion`(机制缺省关,preset 里开):它与 `minHypotheses`
+			 * 是两条不同的立场,所以不共用一个键。另外它**只在知识模式下生效**——
+			 * 没有登记的命题就没有「形态」可谈,那时拦下来的只是一句空话。
+			 */
+			if (CFG.requireTypedPromotion && derived.knowledge.mode === 'knowledge') {
+				const threshold = levelIndexOf(goal.promote_at_level)
+				/** 与下面那段升格循环**逐字同一套谓词**:将要升格的就是这几条,一条不多一条不少。 */
+				const promotable = derived.hypotheses.filter(
+					(hypothesis) =>
+						(hypothesis.status === 'alive' || hypothesis.status === 'proposed') &&
+						(hypothesis.refutations ?? 0) === 0 &&
+						levelIndexOf(hypothesis.supportedLevel) >= threshold,
+				)
+				const untyped = promotable.filter((hypothesis) => !Array.isArray(hypothesis.assertions) || hypothesis.assertions.length === 0)
+				if (untyped.length > 0) {
+					return fail(
+						'claims_untyped',
+						`有 ${untyped.length} 条命题已经验到门槛、却**没有断言的形态**,再往下就是散文升格:\n${untyped
+							.map((hypothesis) => `- ${hypothesis.id}(${hypothesis.supportedLevel}):${hypothesis.claim}`)
+							.join('\n')}\n把结论写成「主词 · 谓词 = 宾语」才进得了实体图,下一轮也才按概念取用得到。两条路:\n① **补形态再结**:词汇里没有对应的概念 / 谓词就先 \`RegisterTerm\` / \`RegisterPredicate\`,再用 \`SetGoal\` 修订目标、把这些命题连断言一起重列一遍(主张原文一字不动就会用回原 id,验到哪一级接着算),然后重新结案;\n② **如实放弃**:这些结论不值得留下形态,就用 \`CloseGoal(outcome="abandoned")\` 说清阻塞收兵。\n别为了让门放行而编一个词——词汇是约定,它将长期约束这个项目怎么写结论。`,
+					)
+				}
+			}
 			const unfinished = plan === null ? [] : plan.steps.filter((step) => step.status === 'open')
 			const syntheticStep = { id: `goal:${goal.id}`, ordinal: 0, do: `核验目标 ${goal.id} 的判据与转写忠实度`, done_criteria: goal.done_criteria, artifacts: [], tests: null }
 			const gate = {
@@ -6439,6 +6551,7 @@ export function apply(ctx, config = {}) {
 		 * 为什么不像过程本体那样只铺一次:那一份随**发布版本**,这一份随**会话**——
 		 * 一个项目今天没用词汇、明天开始用,货架必须自己长出来,而不是等人记得去建。
 		 * 它也不进卡:货架的位置在提示词里说一次就够,每拍重复就是往上下文里灌水。
+		 * 所有权判据(子会话不写)在写入口——见 `ensureDomainShelf`。
 		 */
 		ensureDomainShelf(host(), sessionId)
 		let brainNote = ''
@@ -6563,6 +6676,7 @@ export function apply(ctx, config = {}) {
 			/**
 			 * **事实货架**:事实变了才重写、才在卡里提一句——**变了才发**,与目录同一条纪律。
 			 * 事实很少变(升格一次),所以这句话在大多数回合里都不出现。
+			 * 所有权判据(子会话不写)在写入口——见 `ensureFactsShelf`。
 			 */
 			const shelf = ensureFactsShelf(sessionId, state)
 			if (shelf !== null) factsNote = `\n- 事实库多了一条(或边界改了):${shelf}——引用前先看它的边界(推翻条件)。`

package/presets/clearai/plugins/prompts.js

@@ -255,16 +255,31 @@ SOP 里的「确认 / 经确认才进入下一 workflow」要求的是一次**
 
 这一节讲**知识用什么语言写**。认识论循环管「凭什么信」,领域本体管「用什么语言说」——两层分开,不许互相代替。
 
+## 进入知识模式后的自主操作顺序(不等用户提醒)
+知识模式的卡里会带一行**相关已知**:当前主张文本命中的概念 / 谓词 / 可复用事实。按这个顺序走:
+1. **先复用**:命中的词条直接用 id 引用,不要重复登记同义词;
+2. **缺什么补什么**:要写断言但谓词不存在时,自主调用 \`RegisterTerm\` / \`RegisterPredicate\` 立最小的一组(每个都带依据);
+3. **命题带形态**:核心假设在 \`SetGoal\` 里连 \`assertions\` 一起写;
+4. **不够精确时才查**:\`QueryKnowledge\` 按概念 / 谓词 / 主体精确取——预检的摘要不够用时用它,不要拿一次空查询断言世上没有。
+
+不要为只出现一次且不需要比较的表述造词——写进 claim 就够了。
+
 ## 什么时候值得先立词
 - 同一件事你会反复写(某个炉次、某个速率、某个指标),而且**两条结论要能互相比对**时:先 \`RegisterTerm\` 立概念,再 \`RegisterPredicate\` 立关系(写清主词域、值域、是否单值)。
 - 词条是**约定**,不是主张:它不需要证据等级,但**依据必填**——哪份材料、哪条事实、谁说的。
 - 反过来:只在这一条结论里出现一次的说法,不必造词——写进 claim 就够了。
 
-## 断言是加法,不是门槛
+## 断言:登记时可省,升格时不可省
 - \`SetGoal\` 的假设可以带 \`assertions\`(主词–谓词–宾语)。**提供即严校**:引用不存在的谓词或概念、宾语形态不合值域、同一事实里自相矛盾,一律在**落账之前**被拒。
-- 不写断言照旧升格,只是显示为「未结构化」。
+- **登记时**不写断言放行(断言在那一刻还只是「你打算怎么验」)。但**要升格成事实的那几条必须有形态**:
+  结案时系统会把「已经验到门槛、却还没有断言」的命题逐条列出来挡下,在派独立评估者之前就挡——
+  这一档拦下来的话,补形态的正当路径是**先用 \`RegisterTerm\` / \`RegisterPredicate\` 立词,
+  再用 \`SetGoal\` 修订目标把这些命题连断言重列一遍**(主张原文一字不动就会用回原 id,验到哪一级接着算),
+  然后重新结案。别为了让门放行而编一个词:词汇是约定,它将长期约束这个项目怎么写结论。
+  确实不值得留下形态的结论,就如实 \`CloseGoal(outcome="abandoned")\`——缺口不许被伪装成 support。
 - 值形态五种:\`statement\` / \`quantity\`(数值 + 单位) / \`formula\` / \`code\`(指向**工作区里真有的文件**,相对路径) / \`reference\`;关系谓词的宾语是另一个概念的 \`instance\`。
-- 断言在**升格那一刻**随事实落地(\`fact/promoted\`),之后不回溯改写旧事实。
+- 断言在**升格那一刻**随事实落地(\`fact/promoted\`),之后不回溯改写旧事实;**事实带着产出它的那条命题 id**(措辞改了也认得出)。
+- 旧账本里那些没有断言的事实照旧可读,标「未结构化」——它们补不上断言,也不算你欠账。
 
 ## 冲突只暴露,不裁决
 两条**未撤回**的已确认事实落在同一单值谓词、同一主体、而客体不同时,系统给出一对冲突读数。它**不撤回任何一侧、也不判断哪条为真**——处置走人门(\`retract_fact\` / \`keep_fact\`)。别把冲突读成「系统说这条错了」。

package/presets/clearai/preset.yml

@@ -1,8 +1,8 @@
 name: ClearAI
 # 预设名册只有这两行元数据,而且**宿主不会替我们本地化**:它只给四个内置 id 做 i18n,
 # 插件给的 name/description **一律原样显示**(见 @deepseek-ai/dsh-client-ui-agent-preset 的
-# presetDisplayText())。所以这里只能自己写死一句话、两种语言并排 ——
-# **一句中文 + 一句英文**,不再堆成两段;长度压在卡片的 clamp 之内(约 4 行)。
+# presetDisplayText())。所以这里只能自己写死、两种语言并排 ——
+# **一句中文 + 一句英文**,各只说一件事;长度压在卡片的 clamp 之内(约 2 行)。
 #
 # ⚠️ description **必须**是块标量(下面那个 `|-`)或者引号,不能写成普通标量:
 # 里面有「冒号 + 空格」时普通标量会被 YAML 读成嵌套映射 —— 而名册对读失败的处理是
@@ -10,4 +10,4 @@ name: ClearAI
 # 显示成目录名 + 「暂无描述」,宿主与我们两边都不报错。0.1.2–0.1.4 都带着这个 bug 发出去过;
 # `verify-package` 里那条「preset.yml 必须真能解析出 name 与 description」就是为此立的门。
 description: |-
-  认识论循环:命题→观测→评估→证据→事实,从答案到证据,从证据到改进。The epistemic loop: proposition → observation → evaluation → evidence → fact — from answers to evidence, from evidence to improvement.
+  利用认识论循环构建可信本体。Build a trustworthy ontology through the epistemic loop.

package/presets/clearai/skills/clearai-loop/SKILL.md

@@ -9,7 +9,22 @@ description: Use when working inside the ClearAI preset and you need the loop's
 
 ## 术语与状态
 
-六个对象是:命题 → 验证 → 观测 → 评估 → 证据 → 事实。等级 L0–L4 只决定**谁可以写裁决**与是否需要人放行。状态不存,全部由台账现算;本技能描述的规则就是当前契约的全部。
+九个对象是:目标 → 计划 → 命题 → 验证 → 观测 → 评估 → 证据 → 事实 → 世界线(等级 L0–L4 只决定**谁可以写裁决**与是否需要人放行)。状态不存,全部由台账现算;本技能描述的规则就是当前契约的全部。
+
+## 知识模式的启动协议(不等用户提醒)
+
+目标一立、命题一登记,系统就把**知识预检**送进运行态卡:当前主张文本命中的概念 / 谓词 / 可复用事实。按这个顺序走:
+
+| 情况 | 动作 |
+|---|---|
+| 命中的词条能表达 | 直接用 id 引用,不重复登记 |
+| 要写断言但谓词不存在 | `RegisterTerm` / `RegisterPredicate` 立最小一组(每个带依据) |
+| 核心假设准备登记 | `SetGoal` 里连 `assertions` 一起写 |
+| 预检摘要不够精确 | `QueryKnowledge` 按概念 / 谓词 / 主体精确取 |
+| 只出现一次且不需要比较 | 保留 claim,不造词 |
+| 单步、一次性、无复用 | 不建本体(普通任务连知识模式都不进) |
+
+**别为了让门放行而编词**:词汇是约定,它将长期约束这个项目怎么写结论。确实不值得留下形态的结论,如实 `CloseGoal(outcome="abandoned")`。
 
 ## 一句话
 
@@ -75,15 +90,3 @@ description: Use when working inside the ClearAI preset and you need the loop's
 - `inconclusive` 是诚实的答案。一次如实推翻假设的步骤照样可以通过验收——不要为了让步骤通过而写 support。
 - 重评产生**新证据**,旧证据不改、不删。
 - 结算单记四列:意图(判据)/ 事实(坐标)/ 评估者 / 差额(依据或缺口)。
-
-## 失败与不确定
-
-- 普通工具错误:同回合返回 `ok=false` 与原因,可继续,自己纠。
-- **效果不确定时先观察**:越过派发边界后结局未知的操作,语义只有一条——先看当前事实,再谈重试。重试的安全前提是「知道上次到底做没做」,这个前提在结局未知时恰恰不成立。
-- 供应商失败被归一化成类型化事实并退避,不会把一次外部抖动升格成整个运行的死亡。
-
-## 上下文纪律(为什么提示词里没有时间)
-
-- 系统提示词**刻意不含当前时间**:它排在稳定区,任何逐调用变化的字节都会让其后的大部分提示词与整段历史失去前缀缓存。时间由每回合的**运行态卡**承载,精确到分钟;真需要精确时间就 `bash date`。
-- 运行态卡只在状态变化时注入,内容是系统算出来的事实,不是你的自述。
-- 读文件带 `limit/offset`;命中过多就缩小范围。不要把整份大文件灌进上下文。