@calcit/procs 0.12.48 → 0.12.49

package/RFCs/07-06-semantic-tree-navigation-rfc.md

@@ -0,0 +1,569 @@
+# RFC: 语义化树形导航与编辑
+
+状态：Draft  
+日期：2026-07-06  
+关联：`cr tree search-replace`、`cr tree show`、`cr query search`、`03-18-query-def-tree-show-chunked-display-plan.md`
+
+---
+
+## 1. 概要
+
+当前 `cr tree` 系列编辑命令在定位子表达式时依赖纯数字点号路径（如 `-p '0.3.2.1'`）。对于人类而言手动数坐标已经不方便，对于 LLM 而言更是结构性难题——LLM 在精确计数方面的可靠性与人类手动数行号相当。
+
+本 RFC 提出 **四层互补方案**，从近到远逐步提升编辑体验：
+
+| 层级   | 方案                | 技术路径                                                                              |
+| ------ | ------------------- | ------------------------------------------------------------------------------------- |
+| **L1** | 展示时自动标注路径  | `tree show` 输出中为每个 list 表达式末尾追加 `; "previous node path: 1.2.3"` 注释节点 |
+| **L2** | 多候选交互确认      | `search-replace` 多匹配时列出候选而非报错                                             |
+| **L3** | 锚点 + 相对偏移搜索 | `search-replace --at ... --child N` 先定位父节点再做子节点替换                        |
+| **L4** | 结构化查询语言      | 语义路径表达式：`path` 开头，裸叶子 + `heading` + `nth` 三步导航                      |
+
+核心设计原则：
+
+- **所有查询表达式均使用 Cirru 语法**（无 Lisp 风格外层括号）
+- **路径表达式中叶子字面量直接表示严格匹配**，表达式取首 token 作为语义算子（`heading` / `nth`）
+- **路径注释使用 `; "previous node path: 1.2.3"` 格式**，作为 list 末尾的注释节点追加，不改变已有子节点索引
+- **锚点使用已有 `calcit.core/noted` macro**，格式为 `noted @anchor:<name> expr`
+
+---
+
+## 2. 动机
+
+### 2.1 现状问题
+
+当前 LLM 编辑 Calcit 代码的标准工作流：
+
+```
+1. cr tree show 'app.main/main!'             → 查看代码结构
+2. LLM 自己数目标表达式的坐标                   → 容易数错
+3. cr tree replace 'app.main/main!' -p '...'  → 可能用错路径
+4. 出错后重新数、重新试                          → 迭代成本高
+```
+
+或者用 `search-replace`：
+
+```
+1. cr tree search-replace 'app.main/main!' --pattern 'old-expr' ...
+   → 报错："Found 3 matches"
+2. LLM 需要切回 tree show 手动辨别是哪个匹配
+3. 回到手动数坐标模式
+```
+
+### 2.2 目标工作流
+
+```
+1. cr tree show 'app.main/main!'  → 输出自动带路径注释
+2. LLM 直接从注释中复制路径          → 不需要数
+3. cr tree replace 'app.main/main!' -p '复制来的路径' ...
+   → 一次成功
+```
+
+或者在多匹配场景：
+
+```
+1. cr tree search-replace ... --pattern '...'
+   → 列出 3 个候选（带路径和上下文）
+2. LLM 用 --pick 0 或 --path 指定
+   → 一次成功
+```
+
+---
+
+## 3. L1：展示时自动标注路径
+
+### 3.1 方案
+
+在 `cr tree show` 的输出中，为每个 **list 节点**的末尾追加一条路径注释。注释放在末尾而非开头，避免插入前导节点导致已有子节点索引偏移。格式为 Cirru 行注释语法：
+
+```cirru
+defn add (a b)
+  &+ a b (; "previous node path: 3.2")
+  ; "previous node path: 3"
+```
+
+实现方式：**在 AST 层面操作**，为每个 `Cirru::List` 的 children 末尾 `push` 一个 comment 节点——即 `Cirru::List`，其首子节点为 `Cirru::Leaf(";")`，后续子节点为注释内容（如 `Cirru::Leaf("previous node path: 1.2.3")`）。格式化时该 list 自然渲染为行注释 `; "previous node path: 1.2.3"`。
+
+### 3.2 命令
+
+```bash
+# 默认行为：纯代码展示，无路径注释
+cr tree show 'app.main/main!'
+
+# 开启路径标注（所有嵌套层级末尾标注路径）
+cr tree show 'app.main/main!' --path-annotations
+```
+
+当展示的节点包含较多子节点（如超过阈值）时，在输出底部提示可用选项：
+
+```
+Tip: This node has 15 children. Use --path-annotations to annotate each child
+     with its path index for easier editing. Use --chunked to split large
+     subtrees into fragments.
+```
+
+### 3.3 输出示例
+
+对于如下源码：
+
+```cirru
+defn process (xs)
+  let
+      ys $ map xs inc
+      zs $ filter ys even?
+    foldl zs 0 add
+```
+
+默认 `cr tree show` 输出（无标注，保持旧行为）：
+
+```cirru
+defn process (xs)
+  let
+      ys $ map xs inc
+      zs $ filter ys even?
+    foldl zs 0 add
+```
+
+`--path-annotations` 时（每个嵌套 list 末尾都追加路径注释）：
+
+```cirru
+defn process (xs)
+  let
+      ys $ map xs inc
+        ; "previous node path: 3.0.0.1.2"
+      ; "previous node path: 3.0.0"
+      zs $ filter ys even?
+        ; "previous node path: 3.0.1.1.2"
+      ; "previous node path: 3.0.1"
+    foldl zs 0 add
+    ; "previous node path: 3.2"
+  ; "previous node path: 3.3"
+```
+
+### 3.4 实现要点
+
+- **AST 层面操作**：调用 `children.push(Cirru::List([Cirru::Leaf(";"), Cirru::Leaf(path_string)]))` 追加注释节点，而非字符串拼接
+- 注释节点格式：`Cirru::List` 首子节点为 `Cirru::Leaf(";")`，后续为内容叶子（如 `"previous node path: 1.2.3"`），渲染为 `; "previous node path: 1.2.3"`
+- `--path-annotations`：递归为所有嵌套 list 末尾追加注释（flag，无参数）
+- 默认不追加任何注释节点，保持旧行为
+- 当展示的节点子节点较多时，底部输出 tip 提示可开启 `--path-annotations` 或 `--chunked`
+- 注释中的路径数字为相对于当前 `-p` 定位 path 的索引
+- 使用 dimmed 颜色渲染注释行，不干扰代码阅读
+- 根节点的 path 为空字符串, 不用显示
+- **末尾追加不改变索引**：注释节点是最后一个 child，不影响已有子节点的相对位置
+
+### 3.5 与 chunked display 的关系
+
+`--path-annotations` 与 `--chunked` 可组合使用，两者独立运作：
+
+- `--chunked`：表达式过大时拆分展示，便于人类阅读整体结构
+- `--path-annotations`：在 chunk 内部或普通展示中标注每个节点的路径坐标
+
+同时启用时：先分片，再在每个 fragment 内部标注路径注释。默认两个都不启用。
+
+---
+
+## 4. L2：多候选交互确认
+
+### 4.1 方案
+
+当 `search-replace` 遇到多个匹配时，**不直接报错退出**，而是：
+
+1. 列出所有候选匹配（带路径、上下文预览、序号）
+2. 允许用户/LLM 通过 `--pick <index>` 或 `--path <path>` 精确指定
+3. 默认行为（无 `--pick` 也无 `--path`）保持不变：报错并要求指定
+
+### 4.2 命令
+
+```bash
+# 多匹配时列出候选
+cr tree search-replace 'app.main/main!' \
+  --pattern 'old-name' \
+  --code 'new-name'
+
+# 输出候选列表后，选择第 2 个候选
+cr tree search-replace 'app.main/main!' \
+  --pattern 'old-name' \
+  --code 'new-name' \
+  --pick 2
+
+# 或直接用路径指定
+cr tree search-replace 'app.main/main!' \
+  --pattern 'old-name' \
+  --code 'new-name' \
+  --at '1.3.0'
+```
+
+### 4.3 候选展示格式
+
+当匹配数 > 1 且未指定 `--pick`/`--at` 时：
+
+```
+Found 3 matches for pattern "old-name":
+
+[0] Path [1.3.0]: "old-name"
+    Context: defn update $ old-name new-name
+    Command: cr tree search-replace 'app.main/main!' --pattern 'old-name' ... --pick 0
+
+[1] Path [2.5.2]: "old-name"
+    Context: let $ old-name x $ do-something old-name
+    Command: cr tree search-replace 'app.main/main!' --pattern 'old-name' ... --pick 1
+
+[2] Path [3.0.1]: "old-name"
+    Context: cond $ = old-name nil $ handle-nil old-name
+    Command: cr tree search-replace 'app.main/main!' --pattern 'old-name' ... --pick 2
+
+Use --pick <index> to select a candidate, or --at '<path>' to specify directly.
+```
+
+### 4.4 实现要点
+
+- `--pick` 和 `--at` 互斥，同时指定时报错
+- 候选按路径深度优先排序（与当前遍历顺序一致）
+- `--pick` 从 0 开始
+- 最多展示 20 个候选，超出部分显示 `... and N more`
+- 该行为同样适用于 `search-replace` 的 list-node 匹配（非仅 leaf）
+
+---
+
+## 5. L3：锚点搜索替换（`search-replace --at`）
+
+### 5.1 方案
+
+扩展 `search-replace`，允许先通过内容匹配定位一个**父节点（锚点）**，然后在锚点的第 N 个子节点中做替换。这样 LLM 只需描述"在哪个定义/哪个 let 里面改"，不需要知道锚点的全局坐标。
+
+### 5.2 命令
+
+```bash
+# 基本形式：在匹配 anchor 的节点的第 N 个子节点中做搜索替换
+cr tree search-replace 'app.main/main!' \
+  --at 'defn add' \
+  --child 2 \
+  --pattern 'old-call' \
+  --code 'new-call'
+
+# 多层锚定：在 anchor 内的第 N 个子节点中再锚定
+cr tree search-replace 'app.main/main!' \
+  --at 'let' \
+  --child 0 \
+  --at 'cond' \
+  --child 1 \
+  --pattern 'old-branch' \
+  --code 'new-branch'
+```
+
+### 5.3 语义
+
+`--at` 与 `--child` 的语义：
+
+- `--at <quoted-code>`：在当前范围内搜索匹配该内容的节点。相当于先做 `search-replace` 的匹配逻辑，**但不替换**。
+- `--child <N>`：从匹配到的锚点进入第 N 个子节点，缩小搜索范围。
+
+组合效果：
+
+```
+search-replace target --at A --child 0 --at B --child 1 --pattern P --code R
+```
+
+等价于：
+
+1. 在 target 中搜索匹配 A 的节点 → 锚点 a
+2. 取 a 的第 0 个子节点 → scope₁
+3. 在 scope₁ 中搜索匹配 B 的节点 → 锚点 b
+4. 取 b 的第 1 个子节点 → scope₂
+5. 在 scope₂ 中搜索匹配 P 的节点 → 替换为 R
+
+### 5.4 约束
+
+- `--at` 在目标范围内**必须唯一匹配**，否则报错列出候选（沿用 L2 的交互逻辑）
+- `--child` 索引从 0 开始
+- 多个 `--at` / `--child` 按出现顺序链式执行
+- `--at` 的参数使用与 L4 路径表达式相同的语义：裸叶子表示严格匹配叶子，表达式取首 token 作为算子（见 §6）
+
+---
+
+## 6. L4：结构化查询语言（Cirru Path Expression）
+
+### 6.1 设计目标
+
+提供一种**完全用 Cirru 语法书写**的语义路径表达式，替代纯数字坐标，让 LLM 和人类都能直观描述"我要编辑哪个节点"。
+
+核心设计：
+
+- 表达式以 `path` 开头
+- **叶子字面量直接表示严格匹配**：`x`、`|hello`、`42` 等裸叶子值表示"当前节点必须是这个叶子"
+- **表达式取首 token 作为语义算子**：`heading`、`nth`
+- 从左到右链式执行，每个选择器在上一个匹配结果上继续缩小范围
+
+选择器只有三种：裸叶子精确匹配叶子值，`heading` 按前缀匹配 list 节点，`nth` 按索引进入子节点。配合 L1 的路径标注（`--path-annotations`）显示各子节点索引，无需额外的搜索型选择器。
+
+### 6.2 选择器类型
+
+#### 6.2.1 叶子严格匹配（裸字面量）
+
+叶子节点直接书写，表示"当前节点必须精确等于此值"：
+
+```cirru
+path defn add
+```
+
+语义：先匹配叶子 `defn`，再匹配叶子 `add`。等价于在 AST 中找连续两个叶子 `defn` `add` 的位置。
+
+- 标识符：`x`、`defn`、`add`
+- 字符串：`|hello`
+- 数字：`42`
+- tag：`:name`
+
+#### 6.2.2 `heading` — 表达式前缀匹配
+
+唯一的 list 节点内容匹配选择器：
+
+```cirru
+path
+  heading def {} :name |add
+```
+
+语义：匹配任何 **前 N 个子节点** 与给定模式一致的 list 节点，允许后面有更多子节点。当无多余子节点时等同于精确匹配。
+
+示例：
+
+```cirru
+; 匹配任意以 def 开头的表达式（def, defn, defrecord, defenum ...）
+path
+  heading def
+
+; 匹配 defn add (a b) (&+ a b)——有 or 没有多余子节点都命中
+path
+  heading defn add (a b)
+    &+ a b
+```
+
+嵌套表达式内的 `(a b)` 递归地用相同规则匹配。
+
+#### 6.2.3 `nth` — 位置导航
+
+```cirru
+path
+  heading defn add (a b)
+    &+ a b
+  nth 2
+```
+
+语义：匹配目标后，进入其第 2 个子节点。
+
+- `nth N`：进入当前匹配节点的第 N 个子节点（从 0 计数）
+
+### 6.3 组合示例
+
+定位 add 函数的第一个 let 绑定：
+
+```cirru
+path
+  heading def {} :name |add
+  nth 2
+  heading let
+  nth 0
+```
+
+等价于：
+
+1. 匹配任意 `def {} :name |add ...` 表达式 → 定位 add 函数
+2. 进入第 2 个子节点（body）
+3. 匹配以 `let` 开头的表达式
+4. 进入第 0 个子节点（bindings）
+
+### 6.4 完整语法规范
+
+```
+path-expr     = "path" selector*
+
+selector      = leaf-literal            ; 叶子严格匹配
+              | list-selector           ; 表达式语义选择器
+
+list-selector = "heading" children  ; 表达式前缀匹配（含精确匹配）
+              | "nth" integer        ; 位置导航
+
+children      = (leaf-literal | nested-expr)*
+nested-expr   = "(" children ")"        ; 在 Cirru 中即缩进嵌套的 list
+
+leaf-literal  = identifier | string-literal | number | tag
+integer        = /\d+/
+```
+
+### 6.5 使用场景
+
+#### 场景 A：定位定义
+
+```bash
+# 搜索 add 函数的 def，拿到路径
+cr query path 'app.main' \
+  --selector 'path
+    heading def {} :name |add'
+
+# 输出: 0 (def 的顶层索引)
+```
+
+#### 场景 B：编辑深层子表达式
+
+```bash
+# 在 add 函数的第一个 let 绑定中搜索并替换
+cr tree search-replace 'app.main/main!' \
+  --path-selector 'path
+    heading def {} :name |add
+    nth 2
+    heading let
+    nth 0' \
+  --pattern 'old-var' \
+  --code 'new-var'
+```
+
+#### 场景 C：批量脚本
+
+```bash
+# 获取路径后用于后续编辑
+PATH=$(cr query path 'app.main' --selector 'path heading def {} :name |init-fn $ nth 2')
+cr tree replace 'app.main/main!' -p "$PATH" --code '...'
+```
+
+### 6.6 与现有路径的互操作
+
+- `cr query path` 输出标准数字路径（如 `1.3.0`），可直接用于 `-p`
+- `--path-selector` 是 `-p` 的超集替代，内部先解析为数字路径再执行
+- 解析失败时给出明确错误信息（哪一步匹配失败、已匹配到的范围、剩余选择器是什么）
+
+### 6.7 选择器语义对比
+
+| 选择器        | 匹配方式                        | 示例                   |
+| ------------- | ------------------------------- | ---------------------- |
+| 裸叶子 `x`    | 当前节点必须是叶子 `x`          | `path defn add`        |
+| `heading ...` | 当前 list 的前 N 个子节点匹配   | `heading def {} :name` |
+| `nth N`       | 导航到当前 list 的第 N 个子节点 | `nth 2`                |
+
+---
+
+## 7. 锚点注释（Source Annotations）
+
+### 7.1 方案
+
+使用已有的 `calcit.core/noted` macro 在源码中定义**命名锚点**，作为编辑时的稳定引用：
+
+```cirru
+defn main! ()
+  noted @anchor:init-state
+    let
+        state $ load-initial-state
+      ; ...
+```
+
+`noted` 是已有 macro，接受 tag 和表达式两个参数。`@anchor:<name>` 作为 tag 标记该表达式，`noted` 在运行时透传表达式的值，锚点信息不参与运行时语义。
+
+锚点附着在表达式上，表达式被移动/复制时锚点跟随。`cr query anchors` 遍历 AST 中所有 `noted` 调用，提取 `@anchor:` 前缀的 tag 及其路径。
+
+### 7.2 命令
+
+```bash
+# 列出所有锚点
+cr query anchors 'app.main'
+
+# 输出：
+#   @anchor:init-state → app.main/main! [1]
+#   @anchor:render-loop → app.main/main! [4.2]
+
+# 用锚点定位
+cr tree show 'app.main/main!' --anchor 'init-state'
+
+# 用锚点编辑：在锚点后插入
+cr tree insert-after 'app.main/main!' \
+  --anchor 'init-state' \
+  --code 'println |loaded'
+```
+
+### 7.3 约束
+
+- 锚点 tag 以 `@anchor:` 前缀标识，在同一 namespace 内必须唯一（不唯一时报错）
+- `noted` 在运行时透传表达式值，锚点不参与运行时语义
+- 锚点跟随表达式移动：`tree delete` / `tree insert` 等操作后，锚点随 `noted` 节点自然位移
+- `cr query anchors` 遍历 AST 中所有 `noted` 调用，提取路径和名称
+
+### 7.4 锚点与路径的对比
+
+| 特性       | 路径 (`-p '1.3.0'`)    | 锚点 (`--anchor 'init-state'`) |
+| ---------- | ---------------------- | ------------------------------ |
+| 稳定性     | 编辑后可能失效         | 跟随代码移动，基本稳定         |
+| 可读性     | 无意义数字             | 语义化名称                     |
+| 设置成本   | 零（自动标注）         | 需要手动添加注释               |
+| LLM 友好度 | 低（需要数坐标或复制） | 高（语义化引用）               |
+
+---
+
+## 8. 实施路线
+
+### Phase 1（最小可行）：L1 + L2
+
+- `tree show --path-annotations`：opt-in 标志，开启后所有嵌套层级标注路径
+- 大节点底部 tip 提示可开启标注或分片
+- `search-replace` 多匹配候选展示（不改默认行为，仅在匹配 > 1 时改进输出）
+
+**预计工作量**：~2-3 天  
+**收益**：LLM 可直接从 show 输出复制路径，多匹配时给出可操作建议
+
+### Phase 2：L3 锚点搜索
+
+- `search-replace --at` / `--child` 链式锚定
+- 将 `search-replace` 从仅 leaf 匹配扩展到 list-node 匹配
+
+**预计工作量**：~3-5 天  
+**收益**：LLM 可用语义描述定位，不再依赖数字路径
+
+### Phase 3：L4 结构化查询语言
+
+- `path` 选择器解析器
+- `cr query path` 命令
+- `--path-selector` 替代 `-p` 的编辑命令集成
+
+**预计工作量**：~5-7 天  
+**收益**：完整的语义化树形查询能力
+
+### Phase 4：锚点注释
+
+- `noted @anchor:<name>` 的识别与提取
+- `cr query anchors` 命令
+- `--anchor` 参数集成到编辑命令
+
+**预计工作量**：~4-6 天  
+**收益**：跨编辑会话的稳定引用
+
+---
+
+## 9. 兼容性
+
+- 所有新参数均为 **opt-in**，现有行为完全保留
+- `--path-annotations` 是 flag，默认关闭，传即开启
+- `--chunked` 默认关闭，需手动开启
+- `--pick` 和 `--path-selector` 与现有 `-p` 互斥
+- 锚点使用已有 `noted` macro，不引入新语法，对现有解析无影响
+
+---
+
+## 10. 开放问题
+
+1. **`--path-annotations` 是否应该默认开启？**
+   - 关闭（当前决定）：保持旧行为，大节点时底部 tip 引导开启
+   - 默认开启：对 LLM 更友好，但改变默认输出
+   - 建议默认关闭 + tip 引导，后续根据使用反馈决定是否改为默认开启
+
+2. **`heading` 是否总是够用？**
+   - `heading` 匹配前 N 个子节点，无多余子节点时等同于精确匹配
+   - 裸叶子处理单值精确匹配
+   - 不提供独立的 `exact` 选择器——链式导航模型中没有它的位置
+   - 后续评估是否需要 `ends-with`、`contains` 等变体
+
+3. **是否需要支持通配符叶子？**
+   - 例：用 `_` 匹配任意单个叶子，`...` 匹配任意剩余子节点
+   - `path heading def _ :name` 匹配任意名称的 def
+   - 当前暂不支持，可作为后续增强
+
+4. **锚点应缓存还是每次遍历 AST？**
+   - 缓存：`cr query anchors` 首次解析后缓存到 snapshot 元数据，编辑后失效重算
+   - 实时遍历：更简单，无需维护缓存一致性
+   - 由于 `noted` 节点在 AST 中自然存在，遍历成本可控，建议先实时遍历

package/RFCs/07-08-ffi-features-and-js-object-type-rfc.md

@@ -0,0 +1,223 @@
+# RFC: `:features` 函数能力标记 + `:js-object` 类型收敛
+
+状态：Draft
+日期：2026-07-08
+
+---
+
+## 1. 概要
+
+在函数 schema 中新增 `:features` 属性（HashSet），标记当前函数可使用的语言能力子集。默认空集合。使用 JS interop 语法（`aget`、`&js-object`、`new` 等）要求函数显式标记 `:features $ #{} :js-ffi`，从类型层面将 FFI 隔离在有限的 binding 函数中。
+
+同步新增 `:js-object` 类型注解，表示 JavaScript FFI 操作产生的外部 opaque 数据，阻断 JS 对象向纯 Calcit 函数的无意识泄露。
+
+## 2. 动机
+
+### 问题
+
+当前 JS FFI 函数（`is_js_syntax_procs` 收录 21 个）在 `codegen::codegen_mode()` 下全局放行，任何函数都可以随意调用：
+
+```cirru
+;; 任意函数都能直接调用 FFI，无任何约束
+defn my-pure-fn (x)
+  aget x |someProp  ;; 静默通过
+  &js-object $ {} (:a 1)  ;; 静默通过
+```
+
+这导致：
+
+- **边界模糊**：无法从代码中区分"纯 Calcit 函数"和"FFI binding 函数"
+- **审查困难**：排查 JS interop 使用点需要全文搜索 21 个函数名
+- **类型不安全**：JS 对象可以自由流经所有函数，静态分析无法追踪外部数据
+- **重构风险**：修改 FFI 层时无法确定影响范围
+
+### 目标
+
+| 目标     | 说明                                                                     |
+| -------- | ------------------------------------------------------------------------ |
+| 权限收敛 | 只有 schema 中声明 `:js-ffi` 的函数才能调用 JS FFI                       |
+| 类型隔离 | `:js-object` 类型标注 JS 对象，跨非 FFI 边界时产生告警                   |
+| 渐进迁移 | 先 warning 后 error，给生态适配时间                                      |
+| 可扩展   | `:features` 设计预留 `:side-effects`、`:async`、`:unsafe` 等未来能力标记 |
+
+## 3. 设计
+
+### 3.1 `:features` — Schema 属性
+
+在 `CalcitFnTypeAnnotation` 中新增 `features` 字段：
+
+```rust
+pub struct CalcitFnTypeAnnotation {
+    pub generics: Arc<Vec<Arc<str>>>,
+    pub where_bounds: Arc<Vec<CalcitGenericBound>>,
+    pub arg_types: Vec<Arc<CalcitTypeAnnotation>>,
+    pub return_type: Arc<CalcitTypeAnnotation>,
+    pub fn_kind: SchemaKind,
+    pub rest_type: Option<Arc<CalcitTypeAnnotation>>,
+    /// Feature flags declared in schema, e.g. `:features $ #{} :js-ffi`
+    pub features: Arc<HashSet<EdnTag>>,
+}
+```
+
+### 3.2 `:js-object` — 类型注解
+
+在 `CalcitTypeAnnotation` 枚举中新增变体：
+
+```rust
+pub enum CalcitTypeAnnotation {
+    // ... 现有变体不变 ...
+    /// JavaScript FFI external object (opaque to Calcit type system)
+    JsObject,
+}
+```
+
+EDN 序列化：tag 名为 `:js-object`。
+
+### 3.3 Canonical Cirru EDN 形态
+
+```cirru
+%{} :CodeEntry
+  :doc "|FFI binding for DOM event handling"
+  :code $ quote
+    defn handle-click (event)
+      let
+          target $ aget event |target
+          value $ aget target |value
+        println value
+  :schema $ :: :fn
+    {}
+      :args $ [] :js-object
+      :return :unit
+      :features $ #{} :js-ffi
+```
+
+一行 Cirru EDN 示例：
+
+```cirru
+(:: :fn ({} (:args ([] :js-object)) (:return :unit) (:features (#{} :js-ffi))))
+```
+
+### 3.4 校验流程
+
+```mermaid
+flowchart TD
+    A[preprocess_expr 符号解析] --> B{调用目标是 JS FFI 函数?}
+    B -->|否| C[正常预处理]
+    B -->|是| D{当前正在编译的 def 有 :js-ffi?}
+    D -->|是| C
+    D -->|否| E[产生 Error/Warning]
+
+    F[函数 A 返回 JsObject] --> G[函数 B 接收 JsObject 作为参数]
+    G --> H{B 的 schema 有 :js-ffi?}
+    H -->|否| I[类型告警: JsObject 流入非 FFI 函数]
+    H -->|是| J[放行]
+```
+
+### 3.5 校验位置
+
+| 校验点            | 位置                                       | 触发条件                                                                            |
+| ----------------- | ------------------------------------------ | ----------------------------------------------------------------------------------- |
+| FFI 函数调用      | `preprocess_expr` → `preprocess_list_call` | head 解析为 `is_js_syntax_procs` 且当前编译上下文中 `defn` 无 `:js-ffi`             |
+| `ns js/...` 语法  | `preprocess_expr` 中 `RawCode(Js, _)` 分支 | 同上的 features 检查                                                                |
+| `JsObject` 跨边界 | `check_user_fn_arg_types`                  | 实参类型为 `JsObject` 且形参 schema 非 `JsObject` 且函数无 `:js-ffi`                |
+| `JsObject` 返回值 | `check_function_return_type`               | 返回值推断为 `JsObject` 且函数 schema 的 `:return` 非 `JsObject` 且函数无 `:js-ffi` |
+
+### 3.6 默认值与兼容
+
+- `:features` 默认 `Arc::new(HashSet::new())`，即空集合 = 无任何特殊能力
+- `:js-object` 类型的默认行为：在无 `:js-ffi` 的函数中作为 `:dynamic` 等效处理（宽松模式），或产生类型告警（严格模式）
+- 第一阶段以 **warning** 形式上线，通过 `--warn-ffi` flag 控制，后续升级为 error
+
+## 4. FFI 函数清单
+
+当前 `is_js_syntax_procs()` 收录的函数，全部受 `:js-ffi` 管控：
+
+| 函数                                    | 用途                 | 返回类型建议               |
+| --------------------------------------- | -------------------- | -------------------------- |
+| `aget` / `js-get`                       | JS 属性读取          | `:js-object` 或 `:dynamic` |
+| `aset` / `js-set`                       | JS 属性写入          | `:unit`                    |
+| `js-delete`                             | JS 属性删除          | `:unit`                    |
+| `exists?`                               | JS 属性存在性检查    | `:bool`                    |
+| `instance?`                             | JS instanceof        | `:bool`                    |
+| `&js-object`                            | 创建 JS 对象         | `:js-object`               |
+| `js-array`                              | 创建 JS 数组         | `:js-object`               |
+| `js-await` / `js-for-await`             | Promise/异步迭代     | `:js-object`               |
+| `new`                                   | JS new 构造          | `:js-object`               |
+| `set!`                                  | JS 赋值              | `:unit`                    |
+| `to-js-data`                            | Calcit → JS 转换     | `:js-object`               |
+| `to-calcit-data`                        | JS → Calcit 转换     | `:dynamic`                 |
+| `extract-cirru-edn` / `to-cirru-edn`    | EDN 序列化           | `:string` / `:dynamic`     |
+| `&raw-code`                             | 原始 JS 代码         | `:js-object`               |
+| `timeout-call`                          | 异步定时             | `:js-object`               |
+| `foldl`                                 | fold-left（JS 实现） | 依赖元素类型               |
+| `load-console-formatter!` / `printable` | 控制台输出           | `:unit`                    |
+
+> **注**：`foldl` 虽然在 JS FFI 列表中，但它是纯函数式的 fold 操作，未来可考虑移出 FFI 列表或单独归类。
+
+## 5. 实现计划
+
+### Phase 1: 数据层（~2h）
+
+- [ ] `CalcitFnTypeAnnotation.features` 字段新增
+- [ ] EDN 序列化 / 反序列化（`to_schema_edn` / `parse_loaded_schema_annotation`）
+- [ ] `CalcitTypeAnnotation::JsObject` 变体新增 + 全量 match 补齐
+- [ ] `JsObject` 的 EDN tag 解析（`:js-object`）
+
+### Phase 2: 校验层（~4h）
+
+- [ ] `preprocess_list_call` 中 FFI 调用权限校验
+- [ ] `preprocess_expr` 中 `ns js/...` 语法的 FFI 权限校验
+- [ ] 编译上下文传递：在 `ensure_ns_def_preprocessed` 链路中追踪当前 `defn` 的 features
+- [ ] `check_user_fn_arg_types` 中 `JsObject` 跨边界告警
+- [ ] `check_function_return_type` 中 `JsObject` 返回值告警
+- [ ] `--warn-ffi` CLI flag（默认开启 warning 模式）
+
+### Phase 3: 类型推断（~2h）
+
+- [ ] `&js-object`、`js-array`、`new` 等 FFI 函数的返回值推断为 `JsObject`
+- [ ] `aget` 对 `JsObject` 参数的接收校验
+- [ ] `to-calcit-data` 作为 `JsObject → Dynamic` 的转换边界
+
+### Phase 4: 迁移与测试（~3h）
+
+- [ ] 现有 `calcit/` 下使用 JS FFI 的测试文件 schema 迁移
+- [ ] 新增 `calcit/test-ffi-features.cirru` 测试用例：
+  - 无 `:js-ffi` 调用 `aget` → 预期 warning/error
+  - 有 `:js-ffi` 调用 `aget` → 预期通过
+  - 无 `:js-ffi` 接收 `JsObject` 参数 → 预期类型告警
+  - 有 `:js-ffi` 接收 `JsObject` → 预期通过
+  - `to-calcit-data` 边界转换后不再需要 `:js-ffi`
+- [ ] 文档更新（`docs/features.md`）
+
+### Phase 5: 严格模式（后续版本）
+
+- [ ] 缺少 `:js-ffi` 的 FFI 调用从 warning 升级为 hard error
+- [ ] `:js-object` 可能扩展到区分 `:js-object` vs `:js-array` vs `:js-promise`
+
+## 6. 风险与缓解
+
+| 风险                                    | 影响               | 缓解                                                 |
+| --------------------------------------- | ------------------ | ---------------------------------------------------- |
+| 现有 Cirru 代码大量使用 FFI 但无 schema | 迁移工作量大       | 先 warning 后 error；提供迁移脚本                    |
+| `foldl` 列入 FFI 引起误报               | 纯函数被标记为 FFI | 考虑将 `foldl` 移出 `is_js_syntax_procs` 或单独分类  |
+| 宏生成的函数自动获取 `:js-ffi`          | 权限继承不明确     | 宏生成函数的 features 从宏定义处显式声明，不自动继承 |
+| 第三方库适配周期长                      | 生态断裂           | 预留至少一个大版本的 warning-only 过渡期             |
+
+## 7. 未来扩展
+
+`:features` 设计为 `HashSet<EdnTag>`，天然支持未来新增能力标记：
+
+| 标记            | 含义                                             |
+| --------------- | ------------------------------------------------ |
+| `:js-ffi`       | 可使用 JS interop 语法（本次实现）               |
+| `:side-effects` | 函数可能产生副作用（未来：配合 effects graph）   |
+| `:async`        | 函数内部使用异步操作（未来：配合 effect 系统）   |
+| `:unsafe`       | 函数绕过了类型检查（未来：配合 unsafe block）    |
+| `:host`         | 函数需要宿主环境 API（未来：配合多 target 编译） |
+
+## 8. 参考资料
+
+- 现有 JS FFI 函数定义：`src/builtins.rs:649` `is_js_syntax_procs()`
+- 现有 Schema 结构：`src/calcit/type_annotation.rs:3826` `CalcitFnTypeAnnotation`
+- 现有预处理入口：`src/runner/preprocess/mod.rs` `preprocess_expr()`
+- 相关 RFC：[Type Slot 机制](./04-13-type-slot-mechanism-rfc.md)、[泛型 `:where` 约束](./05-31-generic-where-bounds-mfs.md)

package/RFCs/README.md

@@ -29,6 +29,7 @@
 | `05-31-generic-where-bounds-mfs.md`                 | Active        | 函数 schema 泛型 `:where` 约束的最小功能规格，先作为主链路开发基线。                      |
 | `06-15-effects-graph-rfc.md`                        | Draft         | `cr analyze effects-graph`：State/Transform/Effect 语义分解图与类型驱动 effect 标注路线。 |
 | `06-29-cr-exec-cli-builtins-rfc.md`                 | **Active**    | `cr exec` + `calcit.cli/*` 内建函数：绕过 Shell 转义的 Cirru 函数调用方案。               |
+| `07-06-semantic-tree-navigation-rfc.md`             | Draft         | 语义化树形导航与编辑：路径标注、多候选交互、锚点搜索替换、结构化查询语言。                |
 
 ## 已执行的清理
 

package/editing-history/2026-07-07-0000-semantic-tree-navigation.md

@@ -0,0 +1,49 @@
+# 语义化树形导航实现 (2026-07-07)
+
+## 变更概要
+
+实现 RFC `07-06-semantic-tree-navigation-rfc.md` 全部四个 Phase。
+
+## 实现功能
+
+### L1: `--path-annotations`
+- `cr tree show` 新增 `--path-annotations` flag
+- 开启后递归为所有嵌套 `Cirru::List` 末尾追加 `; "previous node path: X.Y.Z"` 注释节点
+- AST 层面操作：`children.push(Cirru::List([Cirru::Leaf(";"), Cirru::Leaf(path_string)]))`
+- 子节点 > 8 时底部 tip 提示可开启
+
+### L2: `--pick` 多候选选择
+- `search-replace` 多匹配时展示带路径、上下文的候选列表
+- `--pick <N>` 直接选择第 N 个候选执行替换
+
+### L4: 语义路径表达式
+- `cr query path <ns> --selector 'path heading ... nth ...'`
+- 三个选择器：裸叶子（精确匹配）、`heading`（前缀匹配）、`nth`（位置导航）
+- `resolve_path_expression` 函数解析并返回数字路径
+
+### L4: `--selector` 限定搜索范围
+- `search-replace --selector 'path ...'` 在语义路径定位的子树内搜索替换
+- 与 `cr query path` 共用同一套选择器语法
+
+### Phase 4: `cr query anchors`
+- 遍历 AST 中 `noted @anchor:<name>` 调用，输出锚点名称和路径
+
+## 修改文件
+
+| 文件 | 变更 |
+|------|------|
+| `src/cli_args.rs` | 新增 `path_annotations`, `pick`, `selector` 字段；新增 `QueryPathCommand`, `QueryAnchorsCommand` |
+| `src/bin/cli_handlers/tree.rs` | `annotate_paths` 函数；`handle_show` 路径标注 + tip；`handle_search_replace` 多候选 + selector |
+| `src/bin/cli_handlers/query.rs` | `resolve_path_expression`(pub), `starts_with_pattern`, `handle_query_path`, `handle_query_anchors`, `find_anchors` |
+| `src/bin/cli_handlers/command_echo.rs` | Path/Anchors 子命令 echo 支持 |
+| `docs/CalcitAgent.md` | 精简引用新功能 |
+| `docs/run/agent-advanced.md` | 详细示例文档 |
+| `RFCs/07-06-semantic-tree-navigation-rfc.md` | 新增 RFC |
+
+## 设计决策
+
+- `--at`/`--child` 链式语法被 `--selector` 替代，代码中已移除
+- `exact` 选择器不纳入——链式导航模型不需要独立精确匹配，`heading` 无多余子节点时等同
+- `sub-path` 选择器不纳入——L1 路径标注让 `nth` 足够
+- 路径注释放在 list 末尾（不破坏已有子节点索引）
+- `Cirru::Leaf` 存原始内容，格式化时自动加引号

package/editing-history/2026-07-08-1650-features-and-js-object-type.md

@@ -0,0 +1,25 @@
+# `:features` function schema + `:js-object` type + CLI simplification
+
+## Changes
+
+### Feature: `:features` and `:js-object` type system
+- Added `features: Arc<HashSet<EdnTag>>` to `CalcitFnTypeAnnotation` for marking function capabilities
+- Added `CalcitTypeAnnotation::JsObject` variant for opaque JS FFI data
+- EDN round-trip for both (`features_to_edn` + `parse_fn_features_from_form`)
+- Manually implemented `PartialOrd`/`Ord`/`Hash` for `CalcitFnTypeAnnotation`
+- `CURRENT_FN_FEATURES` thread-local + `lookup_def_schema` fallback for FFI checking
+- `as_fn()` helper on `CalcitTypeAnnotation`
+- `#{}` hashset support in `schema_cirru_to_edn`
+- `:features` field validation in `validate_schema_for_write`
+- All direct FFI callers marked with `:features $ #{} :js-ffi`
+
+### Refactor: CLI simplification
+- Removed `--json` option and `--json-input` switch from all edit/tree subcommands
+- Auto-detect JSON (`[` prefix) vs Cirru EDN (`quote` prefix) in `parse_input_to_cirru`
+- Simplified `read_code_input` to `(file, code)` params; stdin fallback
+- Removed `json()`/`json_input()` from `InsertOperation` trait
+- Simplified `CodeInputParts` to only carry `file`+`code`
+- Added stdin mention to all edit subcommand help texts
+- Updated agent docs (CalcitAgent.md, agent-advanced.md, cirru-syntax.md, edit-tree.md)
+- Cleaned up stale short flag mentions (`-j`, `-J`, `-e`)
+- Changed js-interop doc blocks to `no-check` to avoid FFI warnings

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.48",
+    "version": "0.12.49",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.7.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.48",
+  "version": "0.12.49",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.7.0",