Files
marqdo/plugins/agent/src/kb.rs
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

1601 lines
50 KiB
Rust
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! OKF agent-kb helpers (plugin-side). No dependency on marqdo `src/host`.
use std::collections::HashMap;
use std::fs;
use std::path::{Path, PathBuf};
use serde_json::{json, Value};
pub fn normalize_goal(raw: &str) -> String {
let t = raw.trim();
let mut out = String::with_capacity(t.len());
let mut prev_space = false;
for c in t.chars() {
if c.is_whitespace() {
if !prev_space && !out.is_empty() {
out.push(' ');
prev_space = true;
}
} else {
out.push(c);
prev_space = false;
}
}
out
}
/// Light rule-based canonicalize (no model): strip standing prefixes, trailing `?`/`?`/`。`.
pub fn canonicalize_goal_str(raw: &str) -> String {
let mut s = raw.trim().to_string();
const PREFIXES: &[&str] = &[
"你是一个智能体,",
"你是一个智能体,",
"你是一个智能体:",
"你是一个智能体:",
"你是一个智能体",
"作为一个智能体,",
"作为一个智能体,",
"作为一个智能体:",
"作为一个智能体:",
"作为一个智能体",
"You are an agent, ",
"You are an agent,",
"You are an agent. ",
"You are an agent.",
"You are an agent ",
"You are an agent",
"As an agent, ",
"As an agent,",
"As an agent ",
"As an agent",
];
for p in PREFIXES {
if let Some(rest) = s.strip_prefix(p) {
s = rest.trim_start().to_string();
break;
}
}
while s.ends_with('?') || s.ends_with('?') || s.ends_with('。') {
s.pop();
while s.ends_with(|c: char| c.is_whitespace()) {
s.pop();
}
}
normalize_goal(&s)
}
pub fn goal_sig_hex(material: &str) -> String {
let mut h: u64 = 5381;
for b in material.as_bytes() {
h = h.wrapping_mul(33).wrapping_add(u64::from(*b));
}
format!("{h:016x}")[..12].to_string()
}
pub fn goal_slug_str(raw: &str) -> String {
let n = normalize_goal(raw);
let mut out = String::new();
for c in n.chars() {
if c.is_ascii_alphanumeric() {
out.push(c.to_ascii_lowercase());
} else if !c.is_ascii()
&& !c.is_whitespace()
&& !matches!(c, '/' | '\\' | ':' | '*' | '?' | '"' | '<' | '>' | '|')
{
if c.is_alphanumeric() {
out.push(c);
} else if !out.is_empty() && !out.ends_with('-') {
out.push('-');
}
} else if !out.is_empty() && !out.ends_with('-') {
out.push('-');
}
}
while out.ends_with('-') {
out.pop();
}
let mut truncated = String::new();
for c in out.chars() {
if truncated.chars().count() >= 48 {
break;
}
truncated.push(c);
}
while truncated.ends_with('-') {
truncated.pop();
}
if truncated.is_empty() {
"task".into()
} else {
truncated
}
}
fn tools_fingerprint(tools: Option<&Value>) -> String {
match tools {
None | Some(Value::Null) => String::new(),
Some(Value::Array(items)) => {
let mut names: Vec<String> = items
.iter()
.filter_map(|v| match v {
Value::String(s) => Some(s.trim().to_string()),
Value::Object(entries) => entries
.get("工具")
.or_else(|| entries.get("name"))
.or_else(|| entries.get("tool"))
.and_then(|v| v.as_str())
.map(|s| s.trim().to_string()),
_ => None,
})
.filter(|s| !s.is_empty())
.collect();
names.sort();
names.join("\n")
}
Some(Value::String(s)) => {
let t = s.trim();
if t.is_empty() {
String::new()
} else {
t.to_string()
}
}
_ => String::new(),
}
}
fn material_for(goal: &str, tools: Option<&Value>) -> String {
let mut material = normalize_goal(goal);
let fp = tools_fingerprint(tools);
if !fp.is_empty() {
material.push('\n');
material.push_str(&fp);
}
material
}
fn resolve_path(rel: &str) -> PathBuf {
let p = PathBuf::from(rel);
if p.is_absolute() {
return p;
}
// Prefer host cwd (entry file directory) via host_query when available.
let base = (|| {
let q = crate::host_query_json("cwd")?;
q.as_str()
.map(PathBuf::from)
.ok_or_else(|| "cwd not text".to_string())
})()
.or_else(|_| std::env::current_dir().map_err(|e| e.to_string()))
.unwrap_or_else(|_| PathBuf::from("."));
base.join(p)
}
fn yaml_escape(s: &str) -> String {
if s.is_empty()
|| s.contains(':')
|| s.contains('#')
|| s.contains('"')
|| s.contains('\'')
|| s.contains('\n')
|| s.starts_with(' ')
{
format!("\"{}\"", s.replace('\\', "\\\\").replace('"', "\\\""))
} else {
s.to_string()
}
}
fn extract_fm_field(source: &str, key: &str) -> Option<String> {
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
let lines: Vec<&str> = source.lines().collect();
if lines.first().map(|l| l.trim()) != Some("---") {
return None;
}
let prefix = format!("{key}:");
for line in lines.iter().skip(1) {
let t = line.trim();
if t == "---" {
break;
}
if let Some(rest) = t.strip_prefix(&prefix) {
return Some(rest.trim().trim_matches('"').to_string());
}
}
None
}
/// Parse Task FM `aliases:` as inline list `[a, b]`, comma string, or YAML `- item` block.
fn extract_fm_aliases(source: &str) -> Vec<String> {
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
let lines: Vec<&str> = source.lines().collect();
if lines.first().map(|l| l.trim()) != Some("---") {
return Vec::new();
}
let mut out = Vec::new();
let mut i = 1usize;
while i < lines.len() {
let t = lines[i].trim();
if t == "---" {
break;
}
if let Some(rest) = t.strip_prefix("aliases:") {
let rest = rest.trim();
if rest.is_empty() {
i += 1;
while i < lines.len() {
let body = lines[i];
let bt = body.trim();
if bt == "---" {
break;
}
if let Some(item) = bt.strip_prefix("- ") {
let a = normalize_goal(item.trim().trim_matches('"'));
if !a.is_empty() {
out.push(a);
}
i += 1;
continue;
}
if bt == "-" {
i += 1;
continue;
}
if !body.starts_with(' ') && !body.starts_with('\t') && !bt.is_empty() {
break;
}
i += 1;
}
break;
}
let inline = rest.trim_matches(|c| c == '[' || c == ']');
for part in inline.split(',') {
let a = normalize_goal(part.trim().trim_matches('"'));
if !a.is_empty() {
out.push(a);
}
}
break;
}
i += 1;
}
out
}
fn format_aliases_yaml(aliases: &[String]) -> String {
if aliases.is_empty() {
return String::new();
}
let mut s = String::from("aliases:\n");
for a in aliases {
s.push_str(" - ");
s.push_str(&yaml_escape(a));
s.push('\n');
}
s
}
fn set_fm_field(source: &str, key: &str, value: &str) -> String {
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
let lines: Vec<&str> = source.lines().collect();
if lines.first().map(|l| l.trim()) != Some("---") {
return source.to_string();
}
let prefix = format!("{key}:");
let mut out = Vec::new();
let mut replaced = false;
let mut in_fm = true;
for (i, line) in lines.iter().enumerate() {
if i == 0 {
out.push((*line).to_string());
continue;
}
if in_fm && line.trim() == "---" {
if !replaced {
out.push(format!("{key}: {value}"));
}
in_fm = false;
out.push((*line).to_string());
continue;
}
if in_fm && line.trim().starts_with(&prefix) {
out.push(format!("{key}: {value}"));
replaced = true;
} else {
out.push((*line).to_string());
}
}
out.join("\n") + if source.ends_with('\n') { "\n" } else { "" }
}
fn kb_rel(kb_dir: &str, parts: &str) -> String {
format!("{}/{}", kb_dir.trim_end_matches('/'), parts)
}
fn resolve_skill_paths(
root: &Path,
sig: &str,
slug_hint: &str,
) -> Option<(PathBuf, PathBuf, PathBuf, String)> {
let tasks_dir = root.join("concepts/tasks");
let skills_dir = root.join("concepts/skills");
let res_dir = root.join("resources");
let sig4 = if sig.len() >= 4 { &sig[..4] } else { sig };
for slug in [slug_hint.to_string(), format!("{slug_hint}-{sig4}")] {
let task = tasks_dir.join(format!("{slug}.md"));
if task.is_file() {
if let Ok(src) = fs::read_to_string(&task) {
let fm_sig = extract_fm_field(&src, "sig");
if fm_sig.as_deref() == Some(sig) || fm_sig.is_none() {
let skill = skills_dir.join(format!("{slug}.md"));
let res = res_dir.join(format!("{slug}.mq.md"));
if skill.is_file() && res.is_file() {
return Some((task, skill, res, slug));
}
}
}
}
}
if tasks_dir.is_dir() {
if let Ok(rd) = fs::read_dir(&tasks_dir) {
for ent in rd.flatten() {
let p = ent.path();
if p.extension().and_then(|e| e.to_str()) != Some("md") {
continue;
}
let Ok(src) = fs::read_to_string(&p) else {
continue;
};
if extract_fm_field(&src, "sig").as_deref() == Some(sig) {
let stem = p.file_stem()?.to_string_lossy().into_owned();
let skill = skills_dir.join(format!("{stem}.md"));
let res = res_dir.join(format!("{stem}.mq.md"));
if skill.is_file() && res.is_file() {
return Some((p, skill, res, stem));
}
}
}
}
}
let task = tasks_dir.join(format!("{sig}.md"));
let skill = skills_dir.join(format!("{sig}.md"));
let res = res_dir.join(format!("{sig}.mq.md"));
if task.is_file() && skill.is_file() && res.is_file() {
return Some((task, skill, res, sig.to_string()));
}
None
}
/// Second-pass exact match: `normalize_goal(query)` equals a Task FM alias.
fn resolve_skill_paths_by_alias(
root: &Path,
goal_norm: &str,
) -> Option<(PathBuf, PathBuf, PathBuf, String)> {
if goal_norm.is_empty() {
return None;
}
let tasks_dir = root.join("concepts/tasks");
let skills_dir = root.join("concepts/skills");
let res_dir = root.join("resources");
if !tasks_dir.is_dir() {
return None;
}
let rd = fs::read_dir(&tasks_dir).ok()?;
for ent in rd.flatten() {
let p = ent.path();
if p.extension().and_then(|e| e.to_str()) != Some("md") {
continue;
}
let Ok(src) = fs::read_to_string(&p) else {
continue;
};
let aliases = extract_fm_aliases(&src);
if !aliases.iter().any(|a| a == goal_norm) {
continue;
}
let stem = p.file_stem()?.to_string_lossy().into_owned();
let skill = skills_dir.join(format!("{stem}.md"));
let res = res_dir.join(format!("{stem}.mq.md"));
if skill.is_file() && res.is_file() {
return Some((p, skill, res, stem));
}
}
None
}
fn unique_slug(root: &Path, base: &str, sig: &str) -> String {
let tasks = root.join("concepts/tasks");
let candidate = tasks.join(format!("{base}.md"));
if !candidate.is_file() {
return base.to_string();
}
if let Ok(src) = fs::read_to_string(&candidate) {
if extract_fm_field(&src, "sig").as_deref() == Some(sig) {
return base.to_string();
}
}
let sig4 = if sig.len() >= 4 { &sig[..4] } else { sig };
format!("{base}-{sig4}")
}
fn llm_free_score(src: &str) -> (bool, i64) {
let lower = src.to_ascii_lowercase();
let has_step = src.contains(".step") || src.contains(".单步") || src.contains("agent.step");
let has_llm = lower.contains("llm.llm")
|| lower.contains("llm.complete")
|| src.contains("大模型")
|| src.contains(".complete");
let free = !has_step && !has_llm;
let len = src.len() as i64;
let quality = if free {
1_000_000 - len.min(999_999)
} else {
100_000 - len.min(99_999)
};
(free, quality)
}
fn write_task_concept(
path: &Path,
sig: &str,
slug: &str,
goal: &str,
now: &str,
aliases: &[String],
) -> Result<(), String> {
if let Some(p) = path.parent() {
fs::create_dir_all(p).map_err(|e| format!("mkdir: {e}"))?;
}
let title: String = goal.chars().take(48).collect();
let mut merged: Vec<String> = Vec::new();
if path.is_file() {
if let Ok(old) = fs::read_to_string(path) {
for a in extract_fm_aliases(&old) {
if !merged.iter().any(|x| x == &a) {
merged.push(a);
}
}
}
}
for a in aliases {
let a = normalize_goal(a);
if a.is_empty() || a == goal {
continue;
}
if !merged.iter().any(|x| x == &a) {
merged.push(a);
}
}
let alias_block = format_aliases_yaml(&merged);
let body = format!(
r#"---
type: Marqdo Task
title: {title}
description: {goal_e}
sig: {sig}
status: stable
tags: [agent-task]
skill: ../skills/{slug}.md
{alias_block}generated:
by: marqdo-agent/plan
at: {now}
verified:
by: marqdo-agent/spawn
at: {now}
---
# Task
See [skill](../skills/{slug}.md).
"#,
title = yaml_escape(&title),
goal_e = yaml_escape(goal),
sig = sig,
slug = slug,
alias_block = alias_block,
now = now,
);
fs::write(path, body).map_err(|e| format!("write task: {e}"))
}
fn write_skill_concept(
path: &Path,
sig: &str,
slug: &str,
goal: &str,
status: &str,
llm_free: bool,
quality: i64,
hits: i64,
now: &str,
meta: &SkillMeta,
) -> Result<(), String> {
if let Some(p) = path.parent() {
fs::create_dir_all(p).map_err(|e| format!("mkdir: {e}"))?;
}
let title: String = goal.chars().take(48).collect();
let mut extra = String::new();
if let Some(ref s) = meta.applies_when {
extra.push_str(&format!("applies_when: {}\n", yaml_escape(s)));
}
if let Some(ref s) = meta.fixtures {
extra.push_str(&format!("fixtures: {}\n", yaml_escape(s)));
}
if let Some(ref s) = meta.sandbox_profile {
extra.push_str(&format!("sandbox_profile: {}\n", yaml_escape(s)));
}
if let Some(ref s) = meta.proof {
extra.push_str(&format!("proof: {}\n", yaml_escape(s)));
}
let body = format!(
r#"---
type: Marqdo Agent Skill
title: {title}
sig: {sig}
resource: ../../resources/{slug}.mq.md
status: {status}
llm_free: {llm_free}
quality: {quality}
hits: {hits}
{extra}generated:
by: marqdo-agent/plan
at: {now}
verified:
by: marqdo-agent/spawn
at: {now}
---
# Skill
Prefer spawning `resource` over re-planning.
"#,
title = yaml_escape(&title),
sig = sig,
slug = slug,
status = status,
llm_free = if llm_free { "true" } else { "false" },
quality = quality,
hits = hits,
extra = extra,
now = now,
);
fs::write(path, body).map_err(|e| format!("write skill: {e}"))
}
#[derive(Default)]
struct SkillMeta {
applies_when: Option<String>,
fixtures: Option<String>,
sandbox_profile: Option<String>,
proof: Option<String>,
}
fn skill_meta_from_src(src: &str) -> SkillMeta {
SkillMeta {
applies_when: extract_fm_field(src, "applies_when"),
fixtures: extract_fm_field(src, "fixtures"),
sandbox_profile: extract_fm_field(src, "sandbox_profile"),
proof: extract_fm_field(src, "proof"),
}
}
fn refresh_index(root: &Path, slug: &str, goal: &str) -> Result<(), String> {
let index = root.join("index.md");
let line = format!(
"- [`{slug}`](concepts/tasks/{slug}.md) — {}\n",
goal.chars().take(60).collect::<String>()
);
if index.is_file() {
let mut cur = fs::read_to_string(&index).map_err(|e| format!("read index: {e}"))?;
let marker = format!("concepts/tasks/{slug}.md");
if !cur.contains(&marker) {
if !cur.ends_with('\n') {
cur.push('\n');
}
cur.push_str(&line);
fs::write(&index, cur).map_err(|e| format!("write index: {e}"))?;
}
} else {
let body = format!(
"---\ntype: Marqdo Catalog\ntitle: agent-kb\ngenerated:\n by: marqdo-agent/plan\n---\n\n# Agent knowledge base\n\n{line}"
);
fs::write(&index, body).map_err(|e| format!("write index: {e}"))?;
}
Ok(())
}
fn now_rfc3339() -> String {
chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true)
}
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
args.get(key)
.and_then(|v| v.as_str())
.ok_or_else(|| format!("missing text `{key}`"))
}
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
args.get(key).and_then(|v| v.as_str()).filter(|s| !s.is_empty())
}
fn opt_tools(args: &Value) -> Option<&Value> {
args.get("tools").filter(|t| !t.is_null())
}
pub fn goal_sig(args: &Value) -> Result<Value, String> {
let goal = arg_text(args, "goal")?;
Ok(Value::String(goal_sig_hex(&material_for(
goal,
opt_tools(args),
))))
}
pub fn goal_slug(args: &Value) -> Result<Value, String> {
let goal = arg_text(args, "goal")?;
Ok(Value::String(goal_slug_str(goal)))
}
pub fn kb_canonicalize(args: &Value) -> Result<Value, String> {
let goal = arg_text(args, "goal")?;
Ok(Value::String(canonicalize_goal_str(goal)))
}
fn arg_bool(args: &Value, key: &str, default: bool) -> bool {
match args.get(key) {
None | Some(Value::Null) => default,
Some(Value::Bool(b)) => *b,
Some(Value::Number(n)) => n.as_i64().unwrap_or(0) != 0,
Some(Value::String(s)) => matches!(
s.trim(),
"1" | "true" | "True" | "TRUE" | "yes" | "Yes" | "on" | "ON"
),
_ => default,
}
}
fn arg_f64(args: &Value, key: &str, default: f64) -> f64 {
match args.get(key) {
None | Some(Value::Null) => default,
Some(Value::Number(n)) => n.as_f64().unwrap_or(default),
Some(Value::String(s)) => s.parse().unwrap_or(default),
_ => default,
}
}
/// Character bigram bag (whitespace stripped). Sparse lexical vectorization — not an embedding model.
pub fn char_bigram_tf(text: &str) -> HashMap<String, f64> {
let chars: Vec<char> = text.chars().filter(|c| !c.is_whitespace()).collect();
let mut m = HashMap::new();
if chars.is_empty() {
return m;
}
if chars.len() == 1 {
m.insert(chars[0].to_string(), 1.0);
return m;
}
for w in chars.windows(2) {
let key = format!("{}{}", w[0], w[1]);
*m.entry(key).or_insert(0.0) += 1.0;
}
m
}
pub fn cosine_tf(a: &HashMap<String, f64>, b: &HashMap<String, f64>) -> f64 {
let mut na = 0.0;
let mut nb = 0.0;
for v in a.values() {
na += v * v;
}
for v in b.values() {
nb += v * v;
}
if na == 0.0 || nb == 0.0 {
return 0.0;
}
let mut dot = 0.0;
if a.len() <= b.len() {
for (k, va) in a {
if let Some(vb) = b.get(k) {
dot += va * vb;
}
}
} else {
for (k, vb) in b {
if let Some(va) = a.get(k) {
dot += va * vb;
}
}
}
dot / (na.sqrt() * nb.sqrt())
}
#[cfg(test)]
fn near_score(query: &str, candidate: &str) -> f64 {
let q = canonicalize_goal_str(query);
let c = canonicalize_goal_str(candidate);
if q.is_empty() || c.is_empty() {
return 0.0;
}
cosine_tf(&char_bigram_tf(&q), &char_bigram_tf(&c))
}
fn task_near_material(src: &str, slug: &str) -> String {
let title = extract_fm_field(src, "title").unwrap_or_else(|| slug.to_string());
let desc = extract_fm_field(src, "description").unwrap_or_default();
let aliases = extract_fm_aliases(src);
let mut parts = vec![title, desc];
parts.extend(aliases);
parts.join(" ")
}
#[derive(Clone)]
struct NearCand {
slug: String,
title: String,
score: f64,
}
fn rank_near_tasks(root: &Path, goal: &str, limit: usize) -> Vec<NearCand> {
let tasks_dir = root.join("concepts/tasks");
let skills_dir = root.join("concepts/skills");
let res_dir = root.join("resources");
if !tasks_dir.is_dir() {
return Vec::new();
}
let q = canonicalize_goal_str(goal);
let qv = char_bigram_tf(&q);
if qv.is_empty() {
return Vec::new();
}
let mut out = Vec::new();
let Ok(rd) = fs::read_dir(&tasks_dir) else {
return Vec::new();
};
for ent in rd.flatten() {
let p = ent.path();
if p.extension().and_then(|e| e.to_str()) != Some("md") {
continue;
}
let Ok(src) = fs::read_to_string(&p) else {
continue;
};
let slug = p
.file_stem()
.map(|s| s.to_string_lossy().into_owned())
.unwrap_or_default();
if slug.is_empty() {
continue;
}
if !skills_dir.join(format!("{slug}.md")).is_file()
|| !res_dir.join(format!("{slug}.mq.md")).is_file()
{
continue;
}
let title = extract_fm_field(&src, "title").unwrap_or_else(|| slug.clone());
let material = task_near_material(&src, &slug);
let score = cosine_tf(&qv, &char_bigram_tf(&canonicalize_goal_str(&material)));
if score > 0.0 {
out.push(NearCand {
slug,
title,
score,
});
}
}
out.sort_by(|a, b| {
b.score
.partial_cmp(&a.score)
.unwrap_or(std::cmp::Ordering::Equal)
.then_with(|| a.slug.cmp(&b.slug))
});
out.truncate(limit.max(1));
out
}
fn lookup_hit_payload(
kb: &str,
root: &Path,
skill_path: &Path,
slug: &str,
match_kind: &str,
query_sig: &str,
score: Option<f64>,
) -> Result<Value, String> {
let skill_src =
fs::read_to_string(skill_path).map_err(|e| format!("kb_lookup read skill: {e}"))?;
let mut status = extract_fm_field(&skill_src, "status").unwrap_or_else(|| "stable".into());
if status == "deprecated" || status == "draft" {
return Ok(Value::Null);
}
let mut llm_free = extract_fm_field(&skill_src, "llm_free")
.map(|s| s == "true" || s == "True")
.unwrap_or(false);
let mut quality = extract_fm_field(&skill_src, "quality")
.and_then(|s| s.parse::<i64>().ok())
.unwrap_or(0);
let hits = extract_fm_field(&skill_src, "hits")
.and_then(|s| s.parse::<i64>().ok())
.unwrap_or(0);
let skill_sig = extract_fm_field(&skill_src, "sig").unwrap_or_else(|| query_sig.to_string());
let res_path = root.join("resources").join(format!("{slug}.mq.md"));
if res_path.is_file() {
if let Ok(res_src) = fs::read_to_string(&res_path) {
let (res_free, res_q) = llm_free_score(&res_src);
if res_free {
llm_free = true;
status = "stable".into();
}
if res_q > quality {
quality = res_q;
}
}
}
let mut out = json!({
"hit": true,
"match": match_kind,
"sig": skill_sig,
"query_sig": query_sig,
"slug": slug,
"status": status,
"llm_free": llm_free,
"quality": quality,
"hits": hits,
"resource": kb_rel(kb, &format!("resources/{slug}.mq.md")),
"task": kb_rel(kb, &format!("concepts/tasks/{slug}.md")),
"skill": kb_rel(kb, &format!("concepts/skills/{slug}.md")),
});
if let Some(s) = score {
if let Some(obj) = out.as_object_mut() {
obj.insert("score".into(), json!((s * 1000.0).round() / 1000.0));
}
}
Ok(out)
}
fn resolve_skill_paths_by_slug(
root: &Path,
slug: &str,
) -> Option<(PathBuf, PathBuf, PathBuf, String)> {
let slug = slug.trim();
if slug.is_empty() {
return None;
}
let task = root.join("concepts/tasks").join(format!("{slug}.md"));
let skill = root.join("concepts/skills").join(format!("{slug}.md"));
let res = root.join("resources").join(format!("{slug}.mq.md"));
if task.is_file() && skill.is_file() && res.is_file() {
Some((task, skill, res, slug.to_string()))
} else {
None
}
}
pub fn kb_lookup(args: &Value) -> Result<Value, String> {
let kb = arg_text(args, "kb_dir")?;
let root = resolve_path(kb);
let tools = opt_tools(args);
// Soft-match REUSE: resolve by explicit slug.
if let Some(slug) = args
.get("slug")
.and_then(|v| v.as_str())
.map(str::trim)
.filter(|s| !s.is_empty())
{
let Some((_task, skill_path, _res, slug)) = resolve_skill_paths_by_slug(&root, slug) else {
return Ok(Value::Null);
};
let query_sig = args
.get("goal")
.and_then(|v| v.as_str())
.map(|g| goal_sig_hex(&material_for(g, tools)))
.unwrap_or_default();
return lookup_hit_payload(kb, &root, &skill_path, &slug, "soft", &query_sig, None);
}
let goal = arg_text(args, "goal")?;
let goal_n = normalize_goal(goal);
let query_sig = goal_sig_hex(&material_for(goal, tools));
let slug_hint = goal_slug_str(goal);
let mut match_kind = "exact";
let mut near_score_hit: Option<f64> = None;
let resolved = resolve_skill_paths(&root, &query_sig, &slug_hint)
.or_else(|| {
match_kind = "alias";
resolve_skill_paths_by_alias(&root, &goal_n)
})
.or_else(|| {
let canon = canonicalize_goal_str(goal);
if canon.is_empty() || canon == goal_n {
return None;
}
match_kind = "canonical";
let sig2 = goal_sig_hex(&material_for(&canon, tools));
let slug2 = goal_slug_str(&canon);
resolve_skill_paths(&root, &sig2, &slug2)
.or_else(|| resolve_skill_paths_by_alias(&root, &canon))
})
.or_else(|| {
if !arg_bool(args, "near_match", false) {
return None;
}
let threshold = arg_f64(args, "near_threshold", 0.78);
let ranked = rank_near_tasks(&root, goal, 8);
let best = ranked.first()?;
if best.score < threshold {
return None;
}
match_kind = "near";
near_score_hit = Some(best.score);
resolve_skill_paths_by_slug(&root, &best.slug)
});
let Some((_task, skill_path, _res, slug)) = resolved else {
return Ok(Value::Null);
};
lookup_hit_payload(
kb,
&root,
&skill_path,
&slug,
match_kind,
&query_sig,
near_score_hit,
)
}
pub fn kb_near_match(args: &Value) -> Result<Value, String> {
let kb = arg_text(args, "kb_dir")?;
let goal = arg_text(args, "goal")?;
let limit = match args.get("limit") {
None | Some(Value::Null) => 8usize,
Some(Value::Number(n)) => n.as_u64().unwrap_or(8) as usize,
Some(Value::String(s)) => s.parse().unwrap_or(8),
_ => 8,
}
.clamp(1, 40);
let root = resolve_path(kb);
let ranked = rank_near_tasks(&root, goal, limit);
let candidates: Vec<Value> = ranked
.iter()
.map(|c| {
json!({
"slug": c.slug,
"title": c.title,
"score": (c.score * 1000.0).round() / 1000.0,
})
})
.collect();
let best = ranked.first().map(|c| {
json!({
"slug": c.slug,
"title": c.title,
"score": (c.score * 1000.0).round() / 1000.0,
})
});
let score = ranked.first().map(|c| (c.score * 1000.0).round() / 1000.0);
Ok(json!({
"candidates": candidates,
"count": ranked.len() as i64,
"best": best,
"score": score,
}))
}
pub fn kb_list_tasks(args: &Value) -> Result<Value, String> {
let kb = arg_text(args, "kb_dir")?;
let limit = match args.get("limit") {
None | Some(Value::Null) => 40usize,
Some(Value::Number(n)) => n.as_u64().unwrap_or(40) as usize,
Some(Value::String(s)) => s.parse().unwrap_or(40),
_ => 40,
}
.clamp(1, 200);
let root = resolve_path(kb);
let tasks_dir = root.join("concepts/tasks");
let skills_dir = root.join("concepts/skills");
let mut tasks: Vec<Value> = Vec::new();
if tasks_dir.is_dir() {
let mut ents: Vec<_> = fs::read_dir(&tasks_dir)
.map_err(|e| format!("list tasks: {e}"))?
.flatten()
.collect();
ents.sort_by_key(|e| e.file_name());
for ent in ents {
if tasks.len() >= limit {
break;
}
let p = ent.path();
if p.extension().and_then(|e| e.to_str()) != Some("md") {
continue;
}
let Ok(src) = fs::read_to_string(&p) else {
continue;
};
let slug = p
.file_stem()
.map(|s| s.to_string_lossy().into_owned())
.unwrap_or_default();
if slug.is_empty() {
continue;
}
let title = extract_fm_field(&src, "title").unwrap_or_else(|| slug.clone());
let description = extract_fm_field(&src, "description").unwrap_or_default();
let aliases = extract_fm_aliases(&src);
let alias_count = aliases.len() as i64;
let skill_path = skills_dir.join(format!("{slug}.md"));
let (status, llm_free, hits) = if skill_path.is_file() {
match fs::read_to_string(&skill_path) {
Ok(sk) => {
let status =
extract_fm_field(&sk, "status").unwrap_or_else(|| "stable".into());
let llm_free = extract_fm_field(&sk, "llm_free")
.map(|s| s == "true" || s == "True")
.unwrap_or(false);
let hits = extract_fm_field(&sk, "hits")
.and_then(|s| s.parse::<i64>().ok())
.unwrap_or(0);
(status, llm_free, hits)
}
Err(_) => ("unreadable".into(), false, 0),
}
} else {
("missing_skill".into(), false, 0)
};
tasks.push(json!({
"slug": slug,
"title": title,
"description": description,
"aliases": aliases,
"alias_count": alias_count,
"status": status,
"llm_free": llm_free,
"hits": hits,
}));
}
}
let count = tasks.len() as i64;
Ok(json!({ "tasks": tasks, "count": count }))
}
pub fn kb_add_alias(args: &Value) -> Result<Value, String> {
let kb = arg_text(args, "kb_dir")?;
let slug = arg_text(args, "slug")?;
let alias = arg_text(args, "alias")?;
let alias_n = normalize_goal(alias);
if alias_n.is_empty() {
return Ok(json!({ "ok": false, "reason": "empty_alias" }));
}
let root = resolve_path(kb);
let path = root.join("concepts/tasks").join(format!("{slug}.md"));
if !path.is_file() {
return Ok(json!({ "ok": false, "reason": "missing_task" }));
}
let src = fs::read_to_string(&path).map_err(|e| format!("read task: {e}"))?;
let sig = extract_fm_field(&src, "sig").unwrap_or_default();
let goal = extract_fm_field(&src, "description")
.or_else(|| extract_fm_field(&src, "title"))
.unwrap_or_default();
let now = now_rfc3339();
write_task_concept(&path, &sig, slug, &goal, &now, &[alias_n.clone()])?;
Ok(json!({ "ok": true, "slug": slug, "alias": alias_n }))
}
pub fn kb_record_hit(args: &Value) -> Result<Value, String> {
let kb = arg_text(args, "kb_dir")?;
let goal = arg_text(args, "goal")?;
let goal_n = normalize_goal(goal);
let tools = opt_tools(args);
let sig = goal_sig_hex(&material_for(goal, tools));
let slug_hint = goal_slug_str(goal);
let root = resolve_path(kb);
let Some((_t, skill_path, _r, slug)) = resolve_skill_paths(&root, &sig, &slug_hint)
.or_else(|| resolve_skill_paths_by_alias(&root, &goal_n))
.or_else(|| {
let canon = canonicalize_goal_str(goal);
if canon.is_empty() || canon == goal_n {
return None;
}
let sig2 = goal_sig_hex(&material_for(&canon, tools));
let slug2 = goal_slug_str(&canon);
resolve_skill_paths(&root, &sig2, &slug2)
.or_else(|| resolve_skill_paths_by_alias(&root, &canon))
})
else {
return Ok(Value::Null);
};
let src = fs::read_to_string(&skill_path).map_err(|e| format!("read skill: {e}"))?;
let status = extract_fm_field(&src, "status").unwrap_or_else(|| "stable".into());
let llm_free = extract_fm_field(&src, "llm_free")
.map(|s| s == "true" || s == "True")
.unwrap_or(false);
let hits = extract_fm_field(&src, "hits")
.and_then(|s| s.parse::<i64>().ok())
.unwrap_or(0)
+ 1;
let next = set_fm_field(&src, "hits", &hits.to_string());
fs::write(&skill_path, next).map_err(|e| format!("write skill hits: {e}"))?;
let every = match args.get("improve_every") {
None | Some(Value::Null) => 0i64,
Some(Value::Number(n)) => n.as_i64().unwrap_or(0),
Some(Value::String(s)) => s.parse().unwrap_or(0),
_ => 0,
};
let improve_due = every > 0
&& status == "candidate"
&& !llm_free
&& hits > 0
&& hits % every == 0;
Ok(json!({
"hits": hits,
"slug": slug,
"sig": sig,
"status": status,
"llm_free": llm_free,
"improve_due": improve_due,
}))
}
/// Run workbook (or FM `proof:` / `fixtures:` path) inside CoW sandbox; discard after.
/// O2: llm_free promote requires this proof to succeed (unless `require_proof=false`).
fn sandbox_proof(workbook: &Path, proof_rel: Option<&str>) -> Result<(bool, String), String> {
let root = workbook
.parent()
.ok_or_else(|| "sandbox_proof: workbook has no parent".to_string())?;
// Always pass an absolute root so host `sandbox_open` does not re-join cwd.
let root_abs = if root.is_absolute() {
root.to_path_buf()
} else {
fs::canonicalize(root).unwrap_or_else(|_| {
std::env::current_dir()
.unwrap_or_else(|_| PathBuf::from("."))
.join(root)
})
};
let root_abs = fs::canonicalize(&root_abs).unwrap_or(root_abs);
let default_name = workbook
.file_name()
.and_then(|s| s.to_str())
.ok_or_else(|| "sandbox_proof: bad workbook name".to_string())?;
let path = proof_rel.unwrap_or(default_name);
let open = crate::host_query_json_args(
"sandbox_open",
&json!({ "root": root_abs.to_string_lossy() }),
)?;
let id = open
.get("id")
.and_then(|v| v.as_str())
.ok_or_else(|| "sandbox_proof: open missing id".to_string())?
.to_string();
let run = crate::host_query_json_args("sandbox_run", &json!({ "id": id, "path": path }));
let _ = crate::host_query_json_args("sandbox_discard", &json!({ "id": id }));
match run {
Ok(r) => {
let ok = r.get("ok").and_then(|v| v.as_bool()).unwrap_or(false);
let detail = r
.get("stderr")
.and_then(|v| v.as_str())
.or_else(|| r.get("stdout").and_then(|v| v.as_str()))
.unwrap_or("")
.to_string();
Ok((ok, detail))
}
Err(e) => Ok((false, e)),
}
}
pub fn kb_promote(args: &Value) -> Result<Value, String> {
let kb = arg_text(args, "kb_dir")?;
let goal = arg_text(args, "goal")?;
let workbook = arg_text(args, "workbook")?;
let goal_n = normalize_goal(goal);
let sig = goal_sig_hex(&material_for(goal, opt_tools(args)));
let base_slug = goal_slug_str(&goal_n);
let root = resolve_path(kb);
let slug = unique_slug(&root, &base_slug, &sig);
let src_path = resolve_path(workbook);
let src = fs::read_to_string(&src_path)
.map_err(|e| format!("kb_promote read workbook: {e}"))?;
let require_proof = args
.get("require_proof")
.and_then(|v| v.as_bool())
.unwrap_or(true);
let proof_rel = extract_fm_field(&src, "proof")
.or_else(|| extract_fm_field(&src, "fixtures"));
if require_proof {
let (ok, detail) = sandbox_proof(&src_path, proof_rel.as_deref())?;
if !ok {
return Ok(json!({
"promoted": false,
"reason": "sandbox_proof_failed",
"detail": detail,
"sig": sig,
"slug": slug,
"workbook": workbook,
"proof": proof_rel.unwrap_or_else(|| src_path.file_name().and_then(|s| s.to_str()).unwrap_or("").to_string()),
}));
}
}
let (llm_free, quality) = llm_free_score(&src);
let status = if llm_free { "stable" } else { "candidate" };
let skill_path = root.join("concepts/skills").join(format!("{slug}.md"));
let mut prev_hits = 0i64;
if skill_path.is_file() {
let old = fs::read_to_string(&skill_path).unwrap_or_default();
prev_hits = extract_fm_field(&old, "hits")
.and_then(|s| s.parse::<i64>().ok())
.unwrap_or(0);
let old_q = extract_fm_field(&old, "quality")
.and_then(|s| s.parse::<i64>().ok())
.unwrap_or(0);
if quality < old_q {
return Ok(json!({
"promoted": false,
"reason": "quality_worse",
"sig": sig,
"slug": slug,
}));
}
}
let res_path = root.join("resources").join(format!("{slug}.mq.md"));
if let Some(p) = res_path.parent() {
fs::create_dir_all(p).map_err(|e| format!("mkdir resources: {e}"))?;
}
fs::write(&res_path, &src).map_err(|e| format!("write resource: {e}"))?;
let now = now_rfc3339();
// Optional extra aliases from caller (JSON array or single string).
let mut extra_aliases: Vec<String> = Vec::new();
if let Some(Value::Array(items)) = args.get("aliases") {
for v in items {
if let Some(s) = v.as_str() {
extra_aliases.push(s.to_string());
}
}
} else if let Some(Value::String(s)) = args.get("aliases") {
extra_aliases.push(s.clone());
}
write_task_concept(
&root.join("concepts/tasks").join(format!("{slug}.md")),
&sig,
&slug,
&goal_n,
&now,
&extra_aliases,
)?;
let meta = skill_meta_from_src(&src);
write_skill_concept(
&skill_path,
&sig,
&slug,
&goal_n,
status,
llm_free,
quality,
prev_hits,
&now,
&meta,
)?;
refresh_index(&root, &slug, &goal_n)?;
Ok(json!({
"promoted": true,
"sig": sig,
"slug": slug,
"resource": kb_rel(kb, &format!("resources/{slug}.mq.md")),
"llm_free": llm_free,
"quality": quality,
"status": status,
"hits": prev_hits,
"proof_ok": true,
"applies_when": meta.applies_when,
"fixtures": meta.fixtures,
"sandbox_profile": meta.sandbox_profile,
}))
}
/// O5: mark a skill concept as `status: quarantine` and keep fixtures path in FM.
pub fn kb_quarantine(args: &Value) -> Result<Value, String> {
let kb = arg_text(args, "kb_dir")?;
let slug = arg_text(args, "slug")?;
let reason = opt_text(args, "reason").unwrap_or("sandbox_or_harness_failed");
let root = resolve_path(kb);
let skill_path = root.join("concepts/skills").join(format!("{slug}.md"));
if !skill_path.is_file() {
return Ok(json!({
"ok": false,
"reason": "skill_not_found",
"slug": slug,
"path": skill_path.to_string_lossy(),
}));
}
let src = fs::read_to_string(&skill_path)
.map_err(|e| format!("kb_quarantine read: {e}"))?;
let mut lines: Vec<String> = Vec::new();
let mut saw_status = false;
let mut in_fm = false;
for line in src.lines() {
let t = line.trim();
if t == "---" {
if !in_fm {
in_fm = true;
lines.push(line.to_string());
continue;
} else {
if !saw_status {
lines.push("status: quarantine".to_string());
}
lines.push(format!("quarantine_reason: {}", yaml_escape(reason)));
in_fm = false;
lines.push(line.to_string());
continue;
}
}
if in_fm && t.starts_with("status:") {
lines.push("status: quarantine".to_string());
saw_status = true;
continue;
}
if in_fm && t.starts_with("llm_free:") {
lines.push("llm_free: false".to_string());
continue;
}
lines.push(line.to_string());
}
let body = lines.join("\n") + "\n";
fs::write(&skill_path, body).map_err(|e| format!("kb_quarantine write: {e}"))?;
Ok(json!({
"ok": true,
"slug": slug,
"status": "quarantine",
"reason": reason,
"path": skill_path.to_string_lossy(),
}))
}
fn extract_result_text(observation: Option<&Value>) -> Option<String> {
let obs = observation?;
if let Some(v) = obs.get("value") {
if let Some(t) = value_as_result_text(v) {
return Some(t);
}
}
let last_ok = obs.get("last_ok")?;
let result_val = match last_ok {
Value::Object(_) => last_ok.get("result")?.clone(),
Value::String(s) => {
let parsed: Value = serde_json::from_str(s).ok()?;
match &parsed {
Value::Object(_) => parsed.get("result")?.clone(),
other => other.clone(),
}
}
_ => return None,
};
value_as_result_text(&result_val)
}
fn value_as_result_text(result_val: &Value) -> Option<String> {
match result_val {
Value::Null => None,
Value::String(t) => {
let t = t.trim();
if t.is_empty() {
None
} else {
Some(t.to_string())
}
}
Value::Number(n) => Some(n.to_string()),
Value::Bool(b) => Some(if *b { "true" } else { "false" }.into()),
_ => None,
}
}
fn marqdo_quoted_text(s: &str) -> String {
let mut out = String::from("\"");
for c in s.chars() {
match c {
'\\' => out.push_str("\\\\"),
'"' => out.push_str("\\\""),
'\n' => out.push_str("\\n"),
'\t' => out.push_str("\\t"),
c => out.push(c),
}
}
out.push('"');
out
}
fn needs_step_solidify(src: &str) -> bool {
src.contains(".step") || src.contains(".单步") || src.contains("worker.step")
}
pub fn workbook_solidify(args: &Value) -> Result<Value, String> {
let path = arg_text(args, "path")?;
let p = resolve_path(path);
let src = fs::read_to_string(&p).map_err(|e| format!("solidify read: {e}"))?;
if !needs_step_solidify(&src) {
return Ok(json!({
"solidified": false,
"reason": "already_solid",
}));
}
let Some(result) = extract_result_text(args.get("observation")) else {
return Ok(json!({
"solidified": false,
"reason": "no_result",
}));
};
let lit = marqdo_quoted_text(&result);
let body = format!(
"---\ntitle: agent workbook\n---\n\n# main\n\n**`result` = {lit}**\n*`result`*\n"
);
fs::write(&p, body).map_err(|e| format!("solidify write: {e}"))?;
Ok(json!({
"solidified": true,
"result": result,
"path": path,
}))
}
pub fn kb_task_files(args: &Value) -> Result<Value, String> {
let kb = arg_text(args, "kb_dir")?;
let goal = arg_text(args, "goal")?;
let _sig = goal_sig_hex(&material_for(goal, opt_tools(args)));
let slug = goal_slug_str(goal);
let root = resolve_path(kb);
let mut files: Vec<Value> = Vec::new();
let res = root.join("resources").join(format!("{slug}.mq.md"));
if res.is_file() {
files.push(Value::String(res.to_string_lossy().into_owned()));
}
let explore = root.join("explore").join(&slug);
if explore.is_dir() {
if let Ok(rd) = fs::read_dir(&explore) {
for ent in rd.flatten() {
let p = ent.path();
let name = p.file_name().and_then(|n| n.to_str()).unwrap_or("");
if name.ends_with(".mq.md") {
files.push(Value::String(p.to_string_lossy().into_owned()));
}
}
}
}
let runs = match args.get("runs_dir").and_then(|v| v.as_str()) {
None => resolve_path(".marqdo/agent-runs"),
Some(s) => resolve_path(s),
};
if runs.is_dir() {
let prefix = format!("workbook-{slug}-");
if let Ok(rd) = fs::read_dir(&runs) {
for ent in rd.flatten() {
let p = ent.path();
let name = p.file_name().and_then(|n| n.to_str()).unwrap_or("");
if name.starts_with(&prefix) && name.ends_with(".mq.md") {
files.push(Value::String(p.to_string_lossy().into_owned()));
}
}
}
}
let count = files.len() as i64;
Ok(json!({
"count": count,
"slug": slug,
"files": files,
}))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn slug_readable() {
let s = goal_slug_str("Reply with exactly the word pong and nothing else.");
assert!(s.contains("pong"), "{s}");
assert!(!s.contains(' '));
}
#[test]
fn sig_stable() {
let a = goal_sig_hex("hello");
assert_eq!(a, goal_sig_hex("hello"));
assert_eq!(a.len(), 12);
}
#[test]
fn canonicalize_strips_standing_prefix() {
let c = canonicalize_goal_str("你是一个智能体,帮我规划明天的行程");
assert_eq!(c, "帮我规划明天的行程");
let c2 = canonicalize_goal_str("你是一个智能体,帮我规划明天的行程?");
assert_eq!(c2, "帮我规划明天的行程");
}
#[test]
fn near_score_trip_near_dupes_high() {
let a = "帮我规划明天行程";
let b = "帮我规划明天的行程";
let s = near_score(a, b);
assert!(s >= 0.78, "expected high near score, got {s}");
let c = "帮我完成明天的行程规划";
let s2 = near_score(b, c);
let unrelated = near_score(b, "明天做什么好");
assert!(
s2 > unrelated,
"paraphrase should beat unrelated: paraphrase={s2} unrelated={unrelated}"
);
}
#[test]
fn near_score_unrelated_low() {
let a = "帮我规划明天的行程";
let b = "明天做什么好";
let s = near_score(a, b);
assert!(s < 0.78, "expected below default threshold, got {s}");
}
#[test]
fn workbook_solidify_rewrites_step_workbook() {
let dir = std::env::temp_dir().join(format!(
"marqdo-solidify-{}",
std::process::id()
));
let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap();
let path = dir.join("wb.mq.md");
fs::write(
&path,
"---\ntitle: t\n---\n\n# main\n\n*`r` = > `worker`.step task=hi *\n**`r`**\n",
)
.unwrap();
let path_s = path.to_string_lossy().into_owned();
let args = json!({
"path": path_s,
"observation": { "value": "pong" }
});
let out = workbook_solidify(&args).unwrap();
assert_eq!(out.get("solidified").and_then(|v| v.as_bool()), Some(true));
let src = fs::read_to_string(&path).unwrap();
assert!(!needs_step_solidify(&src), "still has step: {src}");
assert!(src.contains("pong"), "{src}");
let again = workbook_solidify(&args).unwrap();
assert_eq!(
again.get("reason").and_then(|v| v.as_str()),
Some("already_solid")
);
let _ = fs::remove_dir_all(&dir);
}
#[test]
fn workbook_solidify_no_result() {
let dir = std::env::temp_dir().join(format!(
"marqdo-solidify-nr-{}",
std::process::id()
));
let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap();
let path = dir.join("wb.mq.md");
fs::write(&path, "*`r` = > `worker`.step task=hi *\n").unwrap();
let path_s = path.to_string_lossy().into_owned();
let args = json!({ "path": path_s });
let out = workbook_solidify(&args).unwrap();
assert_eq!(out.get("solidified").and_then(|v| v.as_bool()), Some(false));
assert_eq!(out.get("reason").and_then(|v| v.as_str()), Some("no_result"));
let _ = fs::remove_dir_all(&dir);
}
}