clearai-dsh 0.3.0 → 0.4.0

package/presets/clearai/plugins/commands.js

@@ -1,199 +0,0 @@
-/**
- * ClearAI 的 `/` 命令:人侧的状态窗,外加一个呈审捷径。
- *
- * 为什么只读:权威账本只有一个写入者(clearai-kernel 的意图工具)。命令是**人**的界面——
- * 人不需要借命令改状态:改状态的动作都有专门的门(计划审阅卡、人门动词、面板按钮)。
- * 所以这四个命令(`goal` / `plan` / `evidence` / `worldline`)只从 `clearai` 读门面
- * 现算现渲染,一个字都不落账。
- *
- * 唯一的例外是 `/plan-review`,而且它也不写账:它把「请重新呈审」这句话结构化地
- * steer 给模型,真正的呈审与授权记号落账仍走模型侧的 `RequestPlanReview` 工具。
- * 为什么不直接在命令里弹审阅卡:授权记号(`plan/confirmed`)只能随工具结果的
- * `meta.mutations` 进日志,命令处理器没有这条通道——这不是限制,是权威边界
- * (test/authority-boundary.test.mjs 钉的就是它)。
- *
- * 数据从哪来:宿主半(ui/lib/index.js)提供的 `clearai` 门面——state/derive/view 都走它,
- * **不从 ui/lib import**:发行物里预设与 ui/ 的相对位置不一样,跨平面 import 装上就炸
- * (分层纪律与内核一致:预设平面与宿主平面互不依赖,共享逻辑各自实现或走服务)。
- * 从会话日志现折的,与面板读的是同一份,不存在「命令看到的是另一份状态」。
- */
-
-export const name = 'clearai-commands'
-export const inject = ['commands']
-
-/** 命令的注册形状,供 test/preset-composition.test.mjs 断言(名字即公共契约)。 */
-export const CLEARAI_COMMANDS = ['goal', 'plan', 'evidence', 'worldline', 'plan-review']
-
-const STEP_STATUS_LABEL = { open: '未交付', advanced: '已交付', void: '已作废' }
-
-/** 人门的引导语:人在 `/` 菜单里能做什么,取决于此刻门开在哪(收件箱就是门,由派生事实算出)。 */
-function gateHints(derived) {
-	const hints = []
-	if (derived.planConfirmationPending) hints.push('/plan-review 重新呈审计划')
-	for (const item of derived.inbox ?? []) {
-		if (item.kind === 'fork_adopt') hints.push(`世界线等你裁决:${item.summary}`)
-		if (item.kind === 'skill_candidate') hints.push(`技能候选等你扶正:${item.summary}`)
-		if (item.kind === 'provisional_review') hints.push(`有一个临时采纳待复核:${item.summary}`)
-		if (item.kind === 'plan_blocked') hints.push(`计划触礁,等你指示:${item.summary}`)
-	}
-	return hints
-}
-
-export function apply(ctx) {
-	const commands = ctx.get('commands')
-	const clearai = () => ctx.get('clearai')
-
-	/** 会话键:与内核同一口径(exec.agent.id → sessionId)。 */
-	const sessionOf = (invocation) => String(invocation.agent?.id ?? '')
-
-	const readState = (invocation) => {
-		const facade = clearai()
-		if (facade === undefined) return { error: 'ClearAI 内核不在这个会话里(命令挂上了,内核没挂上)。' }
-		const sessionId = sessionOf(invocation)
-		const state = facade.state(sessionId)
-		return { sessionId, state, derived: facade.derive(sessionId) }
-	}
-
-	commands.register({
-		name: 'goal',
-		description: '当前认识论目标:主张、判据、候选假设与各自的状态(只读,从账本现算)',
-		handler: (invocation) => {
-			const { state, derived, error } = readState(invocation)
-			if (error !== undefined) return { kind: 'error', text: error }
-			if (state.goal === null) return { kind: 'success', text: '还没有立目标。让模型用 SetGoal 立一个(带判据与至少两条候选假设)。' }
-			const lines = [
-				`目标(v${state.goal.revision} · ${state.goal.status}):${state.goal.claim}`,
-				`判据:${state.goal.done_criteria}`,
-				'',
-				`完成度(派生):${derived.progress === null ? '—' : `${Math.round(derived.progress * 100)}%`} · 阶段:${derived.phase ?? '—'}`,
-				'',
-				'候选假设:',
-			]
-			for (const hypothesis of derived.hypotheses) {
-				const marks = [`状态 ${hypothesis.status}`]
-				if (hypothesis.supportedLevel !== null) marks.push(`支持到 ${hypothesis.supportedLevel}`)
-				if (hypothesis.refutations > 0) marks.push(`推翻 ${hypothesis.refutations} 次`)
-				if (hypothesis.inconclusive > 0) marks.push(`无法判定 ${hypothesis.inconclusive} 次`)
-				lines.push(`- [${hypothesis.id}] ${hypothesis.claim}(${marks.join(' · ')})`)
-				lines.push(`  推翻条件:${hypothesis.refute_when}`)
-			}
-			if (derived.hypotheses.length === 0) lines.push('(这条目标没带假设——它是在下限落地之前立的)')
-			return { kind: 'success', text: lines.join('\n') }
-		},
-	})
-
-	commands.register({
-		name: 'plan',
-		description: '活动计划:步骤状态与授权记号(只读,从账本现算)',
-		handler: (invocation) => {
-			const { state, derived, error } = readState(invocation)
-			if (error !== undefined) return { kind: 'error', text: error }
-			const plan = state.plans.find((candidate) => candidate.status === 'active') ?? null
-			if (plan === null) {
-				const closed = state.plans.length
-				return { kind: 'success', text: closed === 0 ? '还没有计划。' : `当前没有活动计划(${closed} 份已收尾)。` }
-			}
-			const stamp = plan.confirmed_at !== null ? `已授权(${plan.confirmed_by === 'user' ? '人批准' : '按行为补写归属'} @ ${plan.confirmed_at})` : '未授权——系统不会自动续跑;显式推进时第一次交付会按事实记下归属'
-			const lines = [
-				`计划 ${plan.id}(${plan.steps.length} 步) · ${stamp}`,
-				'',
-				...plan.steps.map((step, index) => {
-					const head = `${index + 1}. [${STEP_STATUS_LABEL[step.status] ?? step.status}] ${step.id}: ${step.do}`
-					const tail = step.status === 'void' ? `\n   作废缘由:${step.voidReason ?? '—'}` : ''
-					return head + tail
-				}),
-			]
-			const hints = gateHints(derived)
-			if (hints.length > 0) lines.push('', `此刻能做的:${hints.join(';')}`)
-			return { kind: 'success', text: lines.join('\n') }
-		},
-	})
-
-	commands.register({
-		name: 'evidence',
-		description: '证据面:评估卡裁决、进行中步骤的交付摘要(只读,从账本现算)',
-		handler: (invocation) => {
-			const { state, derived, error } = readState(invocation)
-			if (error !== undefined) return { kind: 'error', text: error }
-			const lines = []
-			const audits = state.audits ?? []
-			if (audits.length > 0) {
-				lines.push('评估卡:')
-				for (const audit of audits.slice(-12)) {
-					const verdict = audit.verdict === null ? '裁决在飞' : (typeof audit.verdict === 'object' ? (audit.verdict.accepted === true ? 'accepted' : `not_accepted${audit.verdict.grade !== undefined ? `(${audit.verdict.grade})` : ''}`) : String(audit.verdict))
-					lines.push(`- ${audit.step ?? '?'}:${verdict}`)
-				}
-			} else {
-				lines.push('还没有评估卡。')
-			}
-			const plan = state.plans.find((candidate) => candidate.status === 'active') ?? null
-			if (plan !== null) {
-				const delivered = plan.steps.filter((step) => step.status === 'advanced')
-				if (delivered.length > 0) {
-					lines.push('', '已交付的步骤(结算单在 clear/evidence/):')
-					for (const step of delivered) lines.push(`- ${step.id}: ${step.do}`)
-				}
-			}
-			if ((state.facts ?? []).length > 0) {
-				lines.push('', '已升格的事实:')
-				for (const fact of state.facts.slice(-8)) lines.push(`- ${fact.text}`)
-			}
-			return { kind: 'success', text: lines.join('\n') }
-		},
-	})
-
-	commands.register({
-		name: 'worldline',
-		description: '世界线:分叉、分支读数与终局(只读,从账本现算)',
-		handler: (invocation) => {
-			const { derived, error } = readState(invocation)
-			if (error !== undefined) return { kind: 'error', text: error }
-			const forks = derived.forks ?? []
-			if (forks.length === 0) return { kind: 'success', text: '还没有分叉。真分歧(跑完才知道谁更好)出现时,模型会用 ForkPlan 开世界线。' }
-			const lines = []
-			for (const fork of forks) {
-				const extra = fork.orphaned ? '(随步骤作古而终止)' : fork.phase === 'deciding' ? '(在等你的裁决——面板或人门卡)' : ''
-				lines.push(`分叉 ${fork.id} [${fork.phase}]${extra}: ${fork.question}`)
-				lines.push(`  尺子:${fork.decideBy?.metric ?? '—'}(取${fork.decideBy?.direction === 'min' ? '最小' : '最大'})`)
-				for (const branch of fork.branches) {
-					const flags = [branch.id === fork.recommended ? '推荐' : null, branch.failed ? '执行失败' : null, branch.unreturned ? '执行者未归' : null, branch.orphaned ? '孤儿' : null].filter((flag) => flag !== null).join(' · ')
-					lines.push(`  - ${branch.label}(${branch.status}${flags === '' ? '' : ` · ${flags}`}) 读数 ${branch.reading ?? '—'}`)
-				}
-				if (fork.merge !== null && fork.merge !== undefined) {
-					const label = fork.branches.find((branch) => branch.id === fork.merge.branch)?.label ?? fork.merge.branch
-					lines.push(`  终局:采纳「${label}」(${fork.merge.by === 'user' ? '人裁决' : '算术收敛'}${fork.merge.provisional === true ? ' · 临时采纳,待复核' : ''})`)
-				}
-			}
-			return { kind: 'success', text: lines.join('\n') }
-		},
-	})
-
-	commands.register({
-		name: 'plan-review',
-		description: '把当前计划重新呈给你审阅(原生审阅卡)。批准才会落授权记号',
-		handler: (invocation) => {
-			const { state, derived, error } = readState(invocation)
-			if (error !== undefined) return { kind: 'error', text: error }
-			const plan = state.plans.find((candidate) => candidate.status === 'active') ?? null
-			if (plan === null) return { kind: 'error', text: '没有活动计划——无可呈审。' }
-			if (derived.planConfirmationPending !== true) {
-				return { kind: 'success', text: `这份计划已有授权(${plan.confirmed_by === 'user' ? '人批准' : '按行为记下的归属'}),不需要重呈。` }
-			}
-			/**
-			 * 呈审本身由模型侧的 RequestPlanReview 做:授权记号只能随工具结果的 meta.mutations
-			 * 落账,命令处理器没有那条通道(这是权威边界,不是缺功能)。所以这里把一句结构化的
-			 * 请求 steer 给模型——与人在输入框里打同一句话等价,只是免打字、带先决检查。
-			 */
-			const message = {
-				id: `clearai-cmd-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
-				role: 'user',
-				content: [{ type: 'text', text: '请用 RequestPlanReview 把当前计划重新呈给我审阅。' }],
-				source: { kind: 'user' },
-			}
-			const agent = invocation.agent
-			if (agent.status === 'running') agent.steer(message)
-			else agent.followup(message)
-			return { kind: 'success', text: '已让模型把计划重新呈给你审(RequestPlanReview)——审阅卡出来时,批准才会落授权记号。' }
-		},
-	})
-}

package/presets/clearai/template/knowledge/README.md

@@ -1,25 +0,0 @@
-# clear/knowledge — 领域知识与项目事实
-
-本目录存放项目级的领域知识和已验证的事实。作为每次任务的高优先级事实源。
-
-## 常见文件
-
-- `business_rules.md` — 业务规则与约束
-- `data_dictionary.md` — 数据字典与字段语义
-- `entity_mapping.md` — 实体映射与拓扑关系
-- `domain_facts.md` — 已验证的领域事实
-
-## Fact 条目模板
-
-```markdown
-## Fact: <标题>
-- Statement: <事实陈述>
-- Evidence: <来源文件/实验结果/工具输出摘要>
-- Scope: <适用范围>
-- Last Verified: <YYYY-MM-DD>
-```
-
-## 写入时机
-
-仅在经验经多次任务验证、上升为项目普遍事实时写入此处。
-更新需谨慎，变更前应有明确的工具输出或实验结果作为证据。

package/presets/clearai/template/memory/README.md

@@ -1,34 +0,0 @@
-# clear/memory — 经验沉淀目录
-
-本目录存放每个 Skill 在当前项目下的经验教训（Lessons）。按能力主题组织，不按日期切分。
-
-## 文件命名规范
-
-`<skill_name>_lessons.md`，例如：
-- `data_cleaning_lessons.md`
-- `feature_engineering_lessons.md`
-- `model_training_lessons.md`
-- `troubleshooting.md`（通用故障排查经验）
-
-## Lesson 条目模板
-
-```markdown
-## Lesson: <简短标题>
-- Context: <任务背景/触发条件>
-- Symptom: <现象>
-- Root Cause: <根因>
-- Fix: <采取动作>
-- Validation: <验证方法与结果>
-- Reuse Hint: <下次何时应优先应用>
-```
-
-## 写入时机
-
-- `ClosePlan` 前：若本次任务产生新经验（工具报错修复、边界条件发现、业务规则确认），必须追加到对应文件。
-- Compact 后摘要中出现 `### 待落地记忆 (Pending Lessons):` 段落时，在下次 `CreatePlan` 前落地写入。
-
-## 晋升规则
-
-满足以下任一条件，可将 Lesson 提升至 `clear/skills/*.md`：
-- 同类任务可直接复用，与具体数据弱相关
-- 具备明确的条件-动作-预期结果三元组

package/presets/clearai/template/project.md

@@ -1,49 +0,0 @@
-<!-- clearai:constitution-schema=clearai.project.v1 -->
-
-# 项目章程
-
-本文件回答三件事：**这个项目在探索什么问题；目前已经知道什么、还不知道什么；一个结论要满足什么条件才算可信。**
-它只保存跨任务稳定的项目事实与验收门槛。单次任务的委托属于 Goal，执行步骤与证据属于 Plan，此处不重复。
-未填写的条目请保留占位文字——占位就是「尚未确定」，不能被当成默认答案或完成证据。
-
-<!-- clearai:section=project-goal -->
-## 1. 项目目标
-
-- **要回答的核心问题**：[用一句话写清本项目最终要回答什么问题、或验证什么命题]
-- **使用者与用途**：[谁会使用这里的结论，用来做什么]
-- **成功的样子**：[项目完成时应存在哪些交付物（报告 / 数据集 / 模型 / 应用），各自达到什么程度]
-- **当前阶段**：[资料理解 / 假设形成 / 数据验证 / 实验验证 / 结论沉淀 —— 随进展更新此行]
-
-<!-- clearai:section=background -->
-## 2. 背景与已知事实
-
-> 只写已被证据支撑的事实，并注明来源；猜测与假设写到第 3 节或工作区的假设清单里。
-
-- **问题背景**：[这个问题为什么值得探索，此前已有哪些工作]
-- **已确认的事实**：[逐条列出，每条附来源（文献 / 数据文件 / 实验记录路径）]
-- **关键未知**：[目前明确不知道、需要本项目回答的点]
-
-<!-- clearai:section=constraints -->
-## 3. 关键约束与假设
-
-- **资源约束**：[可用数据、算力、实验条件、时间预算]
-- **方法约束**：[必须使用 / 不得使用的方法、数据许可与伦理边界]
-- **工作假设**：[当前依赖但尚未验证的假设，逐条列出并标注验证计划]
-
-<!-- clearai:section=evidence -->
-## 4. 证据与验收标准
-
-> 一个结论只有满足下面的门槛才能写进「已确认的事实」或最终交付物。
-
-- **证据分级**：[本项目认可哪些证据形态及其强弱次序，如：可复现实验 > 数据统计检验 > 文献佐证 > 推理论证]
-- **验收标准**：[每类交付物的通过条件；写成可检验的判据，而不是形容词]
-- **可复现要求**：[结论对应的数据、脚本、参数应存放在何处，他人如何复跑]
-- **升格门槛**：[达到哪一级（L0–L4）的支持证据且无推翻，假设即成为事实；默认 L3。各等级在本项目里具体指什么，见仓库 docs/verification-loop.md 第 3 节]
-
-<!-- clearai:section=status -->
-## 5. 当前状态
-
-- **最近里程碑**：[最近完成并通过验收的一步及其证据位置]
-- **进行中**：[当前正在推进的工作与预期产出]
-- **已知风险 / 阻塞**：[可能推翻现有结论或阻塞进展的因素]
-- **变更记录**：[本章程的重要修订，一行一条：日期 + 改了什么 + 原因]

package/presets/clearai/template/skills/README.md

@@ -1,37 +0,0 @@
-# Skills 索引
-
-本目录存放项目可用的 Skill。每个 Skill 一个子目录，入口为其中的 `SKILL.md`。
-按需加载：先在此索引确认「该用哪个」，再打开对应 `SKILL.md` 获取完整方法。
-
-## 方法学
-
-- `exploration-loop` — 探索方法学骨架：假设 → 便宜验证 → 昂贵验证的证据升格循环；开始任何未知问题探索前先读。
-- `scientific-brainstorming` — 开放式科研脑暴与发散创意；还没有具体观察、需要先扩大候选空间时用。
-- `hypothesis-generation` — 把观察/文献线索收敛成可证伪的竞争假设与验证计划。
-- `scientific-critical-thinking` — 评估证据可信度与偏倚；交叉验证检索结果、给来源分级时用。
-- `what-if-oracle` — 多分支情景推演（最好/最可能/最坏/二阶效应）；方案变更或路线抉择前做压力测试。
-
-## 调研与文献
-
-- `domain-presearch` — 领域背景快速预研；进入新问题域时先摸清全貌与关键玩家/流派。
-- `process-presearch` — 目标流程/系统的预研；需要先弄懂一条流程（实验、业务、自然过程）怎么运转时用。
-- `literature-review` — 系统性文献综述（多库检索、主题综合、引用核验）。
-- `paper-lookup` — 单篇论文定位与获取（DOI/标题/作者精确查找）。
-- `citation-management` — 引用元数据核验与 BibTeX 管理。
-- `process-understanding-extraction` — 从流程类资料中做可审计的理解抽取与制图（叙述定位、边界单元、拓扑骨架）。
-
-## 数据与分析
-
-- `exploratory-data-analysis` — 首次拿到数据文件时的结构/质量/分布初探与 EDA 报告。
-- `data-qa-analysis` — 观测/实验数据的质量核查（来源清点、对齐、异常与可用性判定）。
-- `data-analysis` — 已了解结构后的深度分析：变量关联、机理对照、领域知识提取。
-- `statistical-analysis` — 假设的统计验证：选检验、查前提、出可审计结论。
-- `chart-diagram-qa` — 图表落盘后的视觉验收与中文标签检查。
-
-## 制品与应用
-
-- `web-artifact` — 单文件自包含网页制品；把结果做成可双击打开、可标注回传的评审件。
-
-## 元能力
-
-- `skill-creator` — 创建或改进 Skill 本身；沉淀新方法为可复用 Skill 时用。

package/presets/clearai/template/skills/chart-diagram-qa/SKILL.md

@@ -1,43 +0,0 @@
----
-name: chart-diagram-qa
-description: |
-  【图表·视觉验收】matplotlib 落盘 lab/diagrams/ 后的 Chart QA 与 CJK 文字验收。适用：含中文标签的图表、信息图、PFD、截图 OCR。不适用：纯文本/代码文件（用 read）；结构化文档（用 read）。
-version: 1.0
-metadata:
-  tier: system
-  origin: template
----
-
-# 图表与信息图视觉验收
-
-## 流程
-
-```
-setup_cjk（预防） → matplotlib（渲染） → lab/diagrams/*.png → read_image（检测）
-```
-
-- **预防**：matplotlib 含中文时先 `setup_cjk()`（`lab/scripts/matplotlib_cjk.py`；代码模板见各 presearch `references/figure_code.md`）。
-- **检测**：`read_image`；`prompt` 必填且须具体，禁止 “describe this image”。
-
-## 何时加载
-
-- 刚用 `bash` + matplotlib/seaborn 落盘 `lab/diagrams/`
-- 需验收中文标签、排查 □/乱码；若处理 PDF，必须先用 `read`，仅在其明确返回扫描/图片型 PDF 提示且正文为空后，才用 `read_image(page=...)` OCR
-
-## 调用 read_image
-
-| 字段 | 要求 |
-|------|------|
-| `path` | workspace 相对路径，如 `lab/diagrams/{slug}_revenue_trend.png` |
-| `prompt` | 必填；Chart QA 以 `"Chart QA: …"` 开头，列出 transcribe/verify 项并附 **Expected** 标签（标题/轴/图例/实体名） |
-
-Chart QA / CJK 细则与示例句式见工具 schema 中 `read_image` 的 `prompt` 参数说明（与 TOOL_PROTOCOL「精准指令」互补，此处不重复清单）。
-
-## 验收后
-
-| 结果 | 动作 |
-|------|------|
-| 全部可读 | 报告中引用 PNG，继续下游 |
-| □ / 乱码 / 缺字 | matplotlib：查 `setup_cjk()` 后重跑；版式问题：调 figsize/布局后重新生成 |
-| 布局截断 | 调 figsize、`bbox_inches='tight'` 或版式参数 |
-| 多张图 | 同一轮并行多个 `read_image`（不同 `path`） |

package/presets/clearai/template/skills/citation-management/SKILL.md

@@ -1,73 +0,0 @@
----
-name: citation-management
-description: |
-  【引用管理·BibTeX】检索论文元数据、DOI→BibTeX、校验与去重。适用：预研/综述报告文末引用统一、交付前引用准确性检查。不适用：全文综述撰写（用 literature-review）；一般网页来源（用 web_search sources 标注）。
-license: MIT license
-metadata:
-  version: 1.0-clearai
-  skill-author: K-Dense Inc. (adapted for ClearAI)
-  tier: system
-  origin: template
-  created_at: '2026-06-12T02:47:05.406842+00:00'
----
-
-# 引用管理 Skill（ClearAI 版）
-
-## 使用边界
-
-- **适用**：构建/清洗 `references.bib`；验证 DOI/PMID；报告交付前引用去重与格式统一。
-- **不适用**：替代 `paper-lookup` 做大规模检索；非学术网页引用（用手动 `[N]` 列表）。
-
-## ClearAI 工具与路径映射
-
-- 元数据获取 → `bash`（CrossRef/PubMed API，见 `scripts/` 若已复制）
-- BibTeX 库 → `lab/knowledge/references.bib`
-- 校验报告 → `lab/knowledge/citation_audit.md`
-- 正式报告引用 → `products/reports/*.md` 文末 `[N]` + bib 键对应
-- 经验回写 → `clear/memory/citation_management_lessons.md`
-
-## 工作流
-
-### 1. 收集待引用项
-
-从 `literature-review`、`domain-presearch` 草稿提取 DOI/标题/URL。
-
-### 2. 元数据解析
-
-- DOI → CrossRef（`curl https://api.crossref.org/works/{doi}`）
-- PMID → PubMed E-utilities
-- 无 DOI：用 `paper-lookup` 或 `web_search` 补全
-
-### 3. 生成 BibTeX
-
-```bibtex
-@article{key2024,
-  title = {...},
-  author = {...},
-  journal = {...},
-  year = {2024},
-  doi = {...}
-}
-```
-
-写入 `lab/knowledge/references.bib`，键名规范：`AuthorYearKeyword`。
-
-### 4. 校验
-
-- 作者/年份/期刊与原文一致
-- 重复键合并
-- 缺失 DOI 标注待补
-
-### 5. 与报告对齐
-
-- Markdown 正文 `[N]` 与 bib 键一一映射
-- 交付前输出 `lab/knowledge/citation_audit.md`：通过/待修/删除
-
-## 常用 bash 片段
-
-```bash
-# CrossRef DOI lookup
-curl -s "https://api.crossref.org/works/10.XXXX/yyyy" | python -m json.tool
-```
-
-更多脚本见已复制 `scripts/` 目录（按需调整输出路径到 `lab/knowledge/`）。