安全自动化工作流

可靠的写入顺序是 context → apply → validate。它让 Agent 或脚本只读取有界上下文，避免基于过期数据写入，并证明提交后的文件仍满足指定 validation level。

以下自动化命令都显式传入 --json。默认输出面向人类阅读，不属于机器合同。

0. 初始化 Eidos Skill

独立 CLI 已经内置智能体工作流使用的 Skill。可以初始化到当前 Space / 项目，也可以安装到当前用户、供所有项目使用：

eidos skills init
eidos skills init --global

不需要 Node.js、npm 或 npx。要初始化其他 Space，可使用 --space <DIR>；如果已有 Skill 文件被编辑，命令会停止，只有显式传入 --force 才会覆盖。

1. 读取有界上下文

eidos --json context tracker.eidos Tasks \
  --fields Title,Status \
  --limit 50

context 返回文件 revision、紧凑 schema 与 logical rows。只有需要 stable ID、 system field、settings、relations 和保存视图时才添加 --full。

筛选使用可移植 JSON，字段可以用名称或 stable ID：

eidos --json context tracker.eidos Tasks \
  --where '{"op":"ne","field":"Status","value":"done"}' \
  --fields Title,Status

ne 是 eq 的 Boolean complement，因此 Status 为空也会匹配。需要排除空值时，再添加 is-not-null 规则。

2. 执行精确修改

把请求保存为 request.json，或通过 stdin 传入：

{
  "revision": "1",
  "table": "Tasks",
  "match": { "_id": "019..." },
  "expect": 1,
  "set": { "Status": "doing" },
  "returning": ["Title", "Status"]
}

eidos --json apply tracker.eidos request.json

revision 拒绝过期工作；expect 防止修改范围意外扩大。CLI 在提交前校验 proposed final state，并返回 returning 指定的记录。

3. 校验已提交文件

eidos --json validate tracker.eidos --level full

任一步返回非零 exit status，都应视为整个工作流失败。不要根据猜测或不完整解析继续执行。

面向智能体的记录与 Schema 意图命令

常见 Schema 修改应优先使用意图命令，而不是手写底层 operation JSON。Table 和 Field 可以使用显示名称或 stable ID；CLI 会在带 revision 检查的事务中先完成解析：

eidos --json field add tracker.eidos \
  --table Tasks --name Due --type date \
  --expected-revision 1 --dry-run

eidos --json relation add tracker.eidos \
  --table Tasks --name Owners --target-table People \
  --cardinality many --on-delete detach \
  --expected-revision 2

eidos --json table update tracker.eidos Tasks \
  --record-label Title --content-field Notes --dry-run

eidos --json field update tracker.eidos Estimate \
  --table Tasks --type integer --dry-run

eidos --json relation update tracker.eidos Owners \
  --table Tasks --cardinality one --dry-run

table update 覆盖名称、设置、记录标签、Markdown 内容字段、位置和默认表修改。 field update 覆盖名称、设置、位置、记录标签选择、存储类型转换和原子化选项改名。字段转换默认使用编辑器相同的推荐策略；先检查 dry-run 分类，只有确定接受 explicit-lossy 影响时才在正式提交中添加 --confirm-lossy。File 字段不能转换，应使用 attachment 命令。relation update 用于修改 forward Relation 的目标表、基数或删除策略。CLI 不暴露字段 Nullable 设置。

当调用方拥有稳定的业务键、但还没有 Row ID 时，使用 rows upsert。它接受一个对象或对象数组：匹配到一条记录就更新，没有匹配就新增。业务键必须是存储字段、值不能为空，并且最多只能匹配一条已有记录：

eidos --json rows upsert tracker.eidos \
  --table Tasks \
  --key "External ID" \
  --values '[{"External ID":"task-1","Title":"Ship CLI","Status":"doing"}]' \
  --expected-revision 3 \
  --dry-run

返回结果中的 plan 会标明每一项是 create 还是 update；dry-run 产生的 Row ID 只是临时规划 ID。去掉 --dry-run 后，整个数组只提交一个 revision。输入数组中有重复业务键，或业务键匹配多条已有记录时，CLI 会拒绝请求且不修改文件。

当一次操作需要在同一张表中混合新增、更新和删除时，使用 rows mutate：

eidos --json rows mutate tracker.eidos \
  --table Tasks \
  --expected-revision 4 \
  --changes '[
    {"kind":"update","rowId":"019...","values":{"Status":"done"}},
    {"kind":"create","clientKey":"new-task","values":{"External ID":"task-2","Title":"Document"}},
    {"kind":"delete","rowId":"019..."}
  ]'

rows mutate 复用 Runtime 的 RowChange 合同，所有修改要么全部提交，要么全部回滚。需要查看计划时添加 --dry-run。当智能体已经掌握完整的 stable ID mutation document 时，仍可使用低层的 rows add/update/delete、schema-apply 和 view-apply。

附件自动化

不要先复制本地文件、再手工拼 File 字段 JSON。attachment import 会把字节暂存到受管的 assets/ 目录，生成规范的 ID、媒体类型、文件大小和 URI，在 revision 检查下更新精确单元格；如果修改失败，还会清理暂存文件和已经暴露的目标文件：

eidos --json attachment import tracker.eidos \
  --table Tasks --row 019... --field Files \
  --source /absolute/path/report.pdf \
  --expected-revision 5

重复 --source 可以在一次 revision 中导入多个文件。只有需要替换整个单元格时才添加 --replace。如果文件已经位于 .eidos 文件所在目录之下，可使用 attachment attach 并传入 --uri assets/name.ext 原地关联，不再复制。

使用 attachment detach --entry 019... 删除精确 entry ID，或显式使用 --all。detach 与 replace 都会保留物理文件，因为其他记录可能仍引用它。下面的命令可检查本地路径、字节数、媒体类型、软链接以及未引用的受管文件：

eidos --json attachment verify tracker.eidos --diagnostics-limit 100

引用损坏时命令返回非零状态。孤儿文件只作为 warning 报告，CLI 不会自动删除。遇到 stale-revision 时，应重新读取目标记录并重新规划，不能直接重放旧的附件修改。

Runtime Formula 与 Lookup

派生字段应使用 canonical Runtime。提交 Formula 前先预览表达式；返回结果包含推导出的类型、依赖字段、诊断信息以及可选的样例值：

Formula 使用固定的 SQLite 3.45 scalar-expression 子集。精确 function whitelist 与 syntax 见 Formula 表达式；不要提交任意 SQL，也不要自行创造 function alias。

eidos --json formula preview tracker.eidos \
  --table Tasks --name Total \
  --formula '"Estimate" * 2' --type integer

Formula 的创建和更新都经过带 revision 检查的 Runtime preflight：

eidos --json formula add tracker.eidos \
  --table Tasks --name Total \
  --formula '"Estimate" * 2' --type integer \
  --expected-revision 4 --dry-run

eidos --json formula update tracker.eidos Total \
  --table Tasks --formula '"Estimate" + 1' --type integer \
  --expected-revision 4

Relation 和目标 Field 已存在后，再创建 Lookup：

eidos --json lookup add tracker.eidos \
  --table Tasks --name OwnerScore \
  --relation-field Owners --target-field Score \
  --aggregate sum --expected-revision 5

table create 的初始 fields 数组可以包含 Formula，并会走相同的 Runtime preflight 路径。 Relation 和 Lookup 需要在引用的 Schema 已存在后再添加。

Lookup 聚合支持 values、first、count、sum、average、min 和 max；需要去重时添加 --distinct。当表中包含 Formula、Lookup 或 inverse Relation 时，query 和 context 会自动通过 Runtime 计算，因此派生字段可以投影、筛选和排序。派生字段不能通过 rows mutation 直接写入。 Runtime 会在提交前拒绝无效类型、缺失目标、过期 plan 和依赖循环。删除 Formula 或 Lookup 属于显式有损操作：先用 dry-run 预览，确认影响后再添加 --confirm-lossy 提交。

低层操作

Schema change 支持在提交前通过真实 transaction path 执行 dry run。

eidos --json schema-apply tracker.eidos \
  --expected-revision 1 \
  --op @schema-change.json \
  --dry-run

schema-apply 也支持 Runtime Schema batch，并会在设置、位置、记录标签、类型转换、选项改名、Relation、Formula 和 Lookup 操作中解析 Table/Field 名称。不同 CLI 进程不会共享 Runtime mutation token，因此已提交修改没有跨命令 undo；需要恢复时，应在获得用户授权后使用 Eidos Lite/Graft 历史或已知良好的文件副本。

从 schema 输出中取得稳定的 Table ID 与 date / datetime Field ID，即可创建 Calendar View：

eidos --json view-apply tracker.eidos - <<'JSON'
{
  "expectedRevision": "2",
  "changes": [{
    "kind": "create-view",
    "clientKey": "calendar",
    "tableId": "019...",
    "name": "Calendar",
    "type": "calendar",
    "query": {},
    "layout": { "dateField": "019..." },
    "position": "1"
  }]
}
JSON

CLI 分配 View ID，并通过 createdViews 返回。持久化 View document 中的 query 与 layout 引用必须使用稳定 Field ID，不能使用显示名称。update-view 可以显式修改名称、类型、query、layout 与 position；delete-view 删除指定的稳定 View ID。