agt0 — 智能体存储技能

一个文件。智能体所需的一切。
本地优先的数据库 + 文件系统 + 内存，全部集成于单个SQLite文件中。

你正在使用 agt0 来持久化数据。请严格遵循本参考文档。

---

设置

bash
npm install -g @seekcontext/agt0
agt0 init <数据库名>
agt0 use <数据库名> # 设为默认（后续命令可省略数据库名）

执行 agt0 use 后，以下所有命令中均可省略 <数据库> 参数。

---

核心模式

存储和检索数据（SQL）

bash

内联SQL

agt0 sql -q CREATE TABLE tasks (id INTEGER PRIMARY KEY, title TEXT, status TEXT)
agt0 sql -q INSERT INTO tasks (title, status) VALUES (构建API, 进行中)
agt0 sql -q SELECT * FROM tasks WHERE status = 进行中

执行SQL文件

agt0 sql -f schema.sql

存储和检索文件（命令行）

bash
agt0 fs put ./data.csv myapp:/data/data.csv # 上传文件
agt0 fs put -r ./src myapp:/src # 上传目录
agt0 fs cat myapp:/data/data.csv # 读取文件
agt0 fs ls myapp:/data/ # 列出目录
agt0 fs get myapp:/data/data.csv ./local.csv # 下载文件
agt0 fs rm myapp:/data/old.csv # 删除文件
agt0 fs mkdir myapp:/data/exports # 创建目录

存储和检索文件（SQL）

sql
SELECT fs_write(/memory/context.md, 用户偏好深色模式);
SELECT fs_read(/memory/context.md);
SELECT fs_append(/logs/session.log, 步骤完成 || char(10));
SELECT fs_exists(/config.json); -- 返回1或0
SELECT fs_size(/config.json); -- 返回字节数

将文件作为表查询（零导入）

sql
-- CSV → 可查询的行（每行以JSON格式存储在_data列中）
SELECT jsonextract(data, $.name) AS 姓名,
jsonextract(data, $.email) AS 邮箱
FROM fs_csv(/data/users.csv)
WHERE jsonextract(data, $.role) = admin;

-- JSONL结构化日志
SELECT json_extract(line, $.level) AS 级别, COUNT(*)
FROM fs_jsonl(/logs/app.jsonl)
GROUP BY 级别;

-- 跨文本文件搜索
SELECT path, line_number, line
FROM fs_text(/src//*.ts)
WHERE line LIKE %TODO%;

-- 目录列表
SELECT path, type, size, mtime FROM fs_list(/data/);

带真实列的CSV/JSONL（虚拟表；仅限单个文件）

当需要原生列名而非 jsonextract(data, ...) 时，使用 CREATE VIRTUAL TABLE ... USING csvexpand(...) / tsvexpand / jsonlexpand。不支持通配符 — 每个CREATE对应一个路径。对于/*.csv模式，请继续使用fscsv/fs_jsonl。

sql
CREATE VIRTUAL TABLE vusers USING csvexpand(/data/users.csv);
SELECT name, email FROM v_users WHERE role = admin;

CREATE VIRTUAL TABLE vlogs USING jsonlexpand(/logs/app.jsonl);
SELECT level, msg FROM v_logs WHERE level = error;

模式在CREATE时固定；文件结构变化时需DROP并重新创建。JSONL列 = 前AGT0FSEXPANDJSONLSCAN_LINES个非空行（默认256）中对象键的排序并集。可选的第二个参数：与TVF相同的JSON（strict、delimiter、header等）。

agt0 sql（仅命令行）： 对于字面单文件路径（无通配符），fscsv/fstsv/fsjsonl会被自动重写，使SELECT *返回真实列。设置AGT0SQLFSEXPAND=0可禁用。在Node中，如需相同重写，可调用包中的expandFsTableSql(sql, db)。

将文件数据导入表

sql
INSERT INTO users (name, email)
SELECT DISTINCT
jsonextract(data, $.name),
jsonextract(data, $.email)
FROM fs_csv(/data/users.csv)
WHERE jsonextract(data, $.email) IS NOT NULL;

---

完整SQL函数参考

标量函数

函数	返回类型	描述
fsread(path)	TEXT	以文本形式读取文件内容
fswrite(path, content)

INTEGER | 写入/覆盖文件，返回字节数 | | fs_append(path, data) | INTEGER | 追加到文件，返回总字节数 | | fs_exists(path) | INTEGER | 路径存在返回1，否则返回0 | | fs_size(path) | INTEGER | 文件大小（字节） | | fs_mtime(path) | TEXT | 最后修改时间（ISO 8601格式） | | fs_remove(path [, recursive]) | INTEGER | 删除文件/目录，返回删除数量 | | fs_mkdir(path [, recursive]) | INTEGER | 创建目录（1=递归创建） | | fs_truncate(path, size) | INTEGER | 截断到指定字节大小 | | fsreadat(path, offset, length) | TEXT | 以UTF-8格式读取字节范围 | | fswriteat(path, offset, data) | INTEGER | 在字节偏移处写入（用NUL填充） |

表值函数

函数	列	描述
fslist(dir)	path, type, size, mode, mtime	列出目录条目
fstext(path [, opts])

linenumber, line, _path | 按行读取文本 | | fscsv(path [, opts]) | linenumber, data, _path | 读取CSV（行→JSON） | | fstsv(path [, opts]) | linenumber, data, _path | 读取TSV（行→JSON） | | fsjsonl(path [, opts]) | linenumber, line, path | 按行读取JSONL |

虚拟表模块（动态列；单一路径，无通配符）：

模块	示例
csvexpand	CREATE VIRTUAL TABLE t USING csvexpand(/data/x.csv [, opts])
tsvexpand

CREATE VIRTUAL TABLE t USING tsvexpand(/data/x.tsv [, opts]) |
| jsonlexpand | CREATE VIRTUAL TABLE t USING jsonlexpand(/logs/x.jsonl [, opts]) |

路径通配符： = 一个段， = 任意深度，? = 一个字符。示例：/logs//.log。

选项（JSON字符串，第二个参数）：exclude（逗号分隔的通配符）、strict（布尔值—失败时处理错误行）、delimiter（字符串）、header（布尔值）。（*_expand模块忽略exclude。）

限制（环境变量）：AGT0FSMAXFILES、AGT0FSMAXFILEBYTES、AGT0FSMAXTOTALBYTES、AGT0FSMAXROWS（每个TVF/扩展扫描的可选上限）、AGT0FSPARSECHUNKBYTES、AGT0FSPREVIEWBYTES（多文件CSV/TSV列发现）、AGT0FSEXPANDJSONLSCANLINES（jsonlexpand的JSONL键发现）、AGT0SQLFSEXPAND（命令行对字面路径fs_* TVF的重写；默认开启）。

---

数据库管理

bash
agt0 list # 列出所有数据库
agt0 inspect <数据库> # 概览（表、文件、大小）
agt0 inspect <数据库> tables # 表列表及行数
agt0 inspect <数据库> schema # 显示CREATE语句
agt0 dump <数据库> -o backup.sql # 完整SQL导出
agt0 dump <数据库> --ddl-only # 仅导出模式
agt0 seed <数据库> schema.sql # 运行SQL文件
agt0 delete <数据库> --yes # 删除数据库
agt