flavor-code 1.4.1 → 1.4.3-beta.2

package/README.md

@@ -40,6 +40,7 @@ Flavor Code connects to OpenAI, Anthropic, or compatible services and works with
 | 🔎 | **Code graph navigation** | A local AST code-graph index (`.flavor/astgraph/`) powers `ast_search`/`ast_callers`/`ast_impact` queries for precise symbol lookup and reachability tracing; `/explain` turns that graph plus git history into newcomer-oriented walkthroughs |
 | 🌿 | **Git-native workflows** | `/commit` drafts a Conventional-Commits message for staged changes and commits after confirmation; `/review` audits uncommitted changes; the read-only `GitHistory` tool explains when and why code changed |
 | 🎨 | **E2E requirement-to-delivery** | From a rough requirement or a design export to a delivered product: PRD, interactive prototype, visual implementation, API integration, autonomous acceptance, and scored delivery (Electron only) |
+| 🌐 | **Agent-driven built-in browser** | The Electron desktop embeds an interactive browser: the agent navigates pages and acts on elements by snapshot reference with `BrowserSnapshot`/`BrowserAct` and friends, every action is annotated in real time via a visual overlay, navigation is guarded against SSRF, and snapshots redact passwords, tokens, and other sensitive fields (Electron only) |
 | 🔁 | **Bounded self-improvement** | Repeated tool failures are captured, deduped, and proposed as suggestions; fixes ship as sandbox-verified plugins or as learned guardrail rules injected into future prompts, with run trends and rule management (`/evolve`) |
 | 🛡️ | **Clear permission boundaries** | Independent control over read, write, Shell, network, and destructive actions; Docker supported |
 
@@ -61,6 +62,8 @@ cd your-project
 flavor
 ```
 
+When you leave the session, the CLI prints the exact command for picking it back up (`flavor --resume <sessionId>`).
+
 **3. Initialize project context**
 
 Run `/init` the first time you enter a project. Flavor analyzes the language, package manager, source directories, and verification commands, then generates a `FLAVOR.md` project guide.
@@ -154,7 +157,7 @@ Runtime behavior and configuration conventions for OAuth PKCE are described in t
 
 ### CLI
 
-Run `flavor` and type natural language. Typing `/` shows built-in commands, plugin commands, and Skills.
+Run `flavor` and type natural language. Typing `/` shows built-in commands, plugin commands, and Skills. A leading `/name` is dispatched only when that name is registered; otherwise the complete text is sent as an ordinary prompt. On macOS, use `Command+C` / `Command+V` for copy and paste; `Ctrl+C` always stops the active turn or exits.
 
 Common commands:
 
@@ -166,6 +169,7 @@ Common commands:
 | `/permissions` | Switch permission modes |
 | `/tasks` | View task plans and sub-agent status |
 | `/compact` | Manually compact long session context |
+| `/paste-image` | Ignore clipboard text and explicitly attach the clipboard image |
 | `/checkpoint`, `/tree` | Save state, view the session tree |
 | `/rewind`, `/unrevert`, `/fork` | Resume or fork sessions |
 | `/memory`, `/remember`, `/forget`, `/forget-cold` | Manage long-term memory; `/forget-cold` purges cold entries and their files |
@@ -213,6 +217,30 @@ Useful commands:
 
 `/co-work` first places both agents in planning and waits for both to accept the same hashed plan and declare READY. Early READY intents are retained, and only the broker's exactly-once START event opens parallel execution. Each agent works only in its own project, receives only its assigned tasks, and reports bounded completion evidence. The broker-selected integration owner verifies all assertions and emits END or FAIL through `CoWorkIntegrate`. Communication uses authenticated, bounded local IPC with no TCP listener; peer input cannot approve tools or access the other workspace. UUID/alias routing and the protocol already support a third active client; durable artifact exchange, broker-restart journaling/recovery, and large-group coordination are later hardening work. See the [CLI pals specification](./docs/specs/2026-08-14-cli-pals-cowork.md).
 
+#### Session, config, and usage management CLI
+
+Non-interactive management commands for scripts, CI, and retrospectives. Like `flavor memory` / `flavor mcp`, these are lightweight entry points that never start the agent runtime, so they cold-start quickly; reading and writing sessions and configuration reuse the same store and schema validation as the interactive mode.
+
+```bash
+# sessions: list / inspect / export / delete
+flavor sessions list                       # saved sessions for this project (newest first)
+flavor sessions show [session-id]          # summarize one session; omit id for the latest
+flavor sessions export <id> --format md --output log.md   # export a transcript (md / json)
+flavor sessions delete <id>                # delete one session
+
+# config: read the effective value, write the project config
+flavor config get context.windowTokens     # read by dot path; secrets are redacted
+flavor config set permissionMode plan      # validated against the merged config before writing; invalid values are not persisted
+flavor config unset language               # remove one key from the project config
+flavor config list --json                  # print the effective (redacted) config
+
+# usage: summarize token and cache usage for the current session
+flavor usage                               # human-readable cache-hit table
+flavor usage --json                        # machine-readable summary
+```
+
+`flavor sessions list/show`, `flavor config list/get`, and `flavor usage` all accept `--json` for scripted consumption.
+
 ### Electron Desktop
 
 ```bash
@@ -299,7 +327,9 @@ Project runtime data lives under `.flavor/`:
 
 Long-term memory distinguishes user preferences, behavioral feedback, project conventions, and external references. Automatic extraction only keeps high-confidence candidates and provides confirm, ignore, and delete actions; secrets, tokens, raw tool output, and model guesses are rejected.
 
-Image prompts support PNG, JPEG, and WebP, with a 5 MiB per-image maximum and up to 5 images per prompt. The desktop app supports picking or drag-and-drop; CLI clipboard images currently work on Windows and macOS.
+Image prompts support PNG, JPEG, and WebP, with a 5 MiB per-image maximum and up to 5 images per prompt. The desktop app supports picking or drag-and-drop; CLI clipboard images currently work on Windows and macOS. Standard CLI paste prefers clipboard text and creates an image attachment only when no usable text flavor is available; use `/paste-image` when both flavors exist and the image is intended.
+
+CLI tool receipts are collapsed by default, and long sessions keep only a viewport-sized window of turns and output items. Press `Ctrl+O` on Windows, Linux, or macOS to expand everything: the render budget is lifted so earlier turns, hidden output items, and full tool details all become visible, with no text truncation. Press it again to return to the compact, responsive view. On macOS, `Command+O` remains available to the terminal or host application.
 
 ## Permissions & Sandbox
 

package/README.zh-CN.md

@@ -40,6 +40,7 @@ Flavor Code 接入 OpenAI、Anthropic 或兼容服务，在受控工作区内使
 | 🔎 | **代码图导航** | 本地 AST 代码图索引（`.flavor/astgraph/`），通过 `ast_search`/`ast_callers`/`ast_impact` 等查询精确定位符号、追踪可达性；`/explain` 结合代码图与 Git 历史，向新人讲解一个符号 |
 | 🌿 | **Git 原生工作流** | `/commit` 为暂存改动生成 Conventional Commits 提交信息并确认提交；`/review` 审查未提交改动；只读 `GitHistory` 工具回答“这段代码为什么是这样” |
 | 🎨 | **E2E 需求到交付** | 从粗需求或设计稿到可交付产品：PRD、交互原型、视觉还原、接口联调、自主验收与评分交付（仅 Electron） |
+| 🌐 | **Agent 内置浏览器** | Electron 桌面端内置可交互浏览器：Agent 通过 `BrowserSnapshot`/`BrowserAct` 等工具导航页面、按元素引用点击与输入，操作以可视化覆盖层实时标注；导航受 SSRF 防护约束，快照自动脱敏密码、token 等敏感字段（仅 Electron） |
 | 🔁 | **有界自进化** | 重复的工具失败被捕获、去重并形成建议；修复以沙箱验证过的插件形式落地，或沉淀为注入后续提示词的 guardrail 规则，并支持运行趋势与规则管理（`/evolve`） |
 | 🛡️ | **明确的权限边界** | 分别控制读、写、Shell、网络和破坏性操作，也可使用 Docker |
 
@@ -61,6 +62,8 @@ cd your-project
 flavor
 ```
 
+退出会话时，CLI 会打印接着上次的恢复命令（`flavor --resume <sessionId>`）。
+
 **3. 初始化项目上下文**
 
 首次进入项目后运行 `/init`。Flavor 会分析语言、包管理器、源码目录和验证命令，并生成 `FLAVOR.md` 项目指南。
@@ -154,7 +157,7 @@ OAuth PKCE 的运行时行为与配置约定见 [PKCE 规范](./docs/specs/pkce-
 
 ### CLI
 
-直接运行 `flavor` 后输入自然语言即可。输入 `/` 会显示内置命令、插件命令和 Skill。
+直接运行 `flavor` 后输入自然语言即可。输入 `/` 会显示内置命令、插件命令和 Skill。只有 `/名称` 命中已注册项时才会分派为命令，否则完整文本会作为普通 prompt 发送。在 macOS 上使用 `Command+C` / `Command+V` 复制和粘贴；`Ctrl+C` 始终用于停止当前回合或退出。
 
 常用命令：
 
@@ -166,6 +169,7 @@ OAuth PKCE 的运行时行为与配置约定见 [PKCE 规范](./docs/specs/pkce-
 | `/permissions` | 切换权限模式 |
 | `/tasks` | 查看任务计划和子 Agent 状态 |
 | `/compact` | 手动压缩长会话上下文 |
+| `/paste-image` | 忽略剪贴板文字，明确添加剪贴板图片 |
 | `/checkpoint`、`/tree` | 保存现场、查看会话树 |
 | `/rewind`、`/unrevert`、`/fork` | 恢复或分叉会话 |
 | `/memory`、`/remember`、`/forget`、`/forget-cold` | 管理长期记忆；`/forget-cold` 清空 cold 记忆及其文件 |
@@ -213,6 +217,30 @@ flavor --pal-name B
 
 `/co-work` 会先让双方进入规划，等待双方接受同一个哈希计划并声明 READY；较早的 READY 意图会被保留，只有 broker 恰好一次的 START 事件才会放行并行执行。每个 Agent 只在自己的项目内工作，只接收分配给自己的任务，并提交有界的完成证据。broker 指定的集成负责人会检查所有断言，再通过 `CoWorkIntegrate` 广播 END 或 FAIL。通信使用经过认证、有大小上限的本机 IPC，不开放 TCP 监听；peer 输入不能代替本机工具审批，也不能访问另一工作区。UUID/别名路由和协议已能支持第三个活动实例；持久化成果物交换、broker 重启日志与恢复、大规模多方协调属于后续强化。详见 [CLI Pals 规范](./docs/specs/2026-08-14-cli-pals-cowork.md)。
 
+#### 会话、配置与用量管理 CLI
+
+面向脚本、CI 和复盘的非交互管理命令，与 `flavor memory` / `flavor mcp` 同属轻量入口，不会启动 Agent 运行时，因此冷启动很快；读写会话与配置复用交互模式相同的存储与 Schema 校验：
+
+```bash
+# 会话：列出 / 查看 / 导出 / 删除
+flavor sessions list                       # 列出当前项目的历史会话（最新在前）
+flavor sessions show [session-id]          # 查看一次会话摘要，省略 id 取最新
+flavor sessions export <id> --format md --output log.md   # 导出会话记录（md / json）
+flavor sessions delete <id>                # 删除一条会话
+
+# 配置：读取生效值、写入项目配置
+flavor config get context.windowTokens     # 按点路径读取，密钥自动脱敏
+flavor config set permissionMode plan      # 写入前先按合并结果校验，非法值不落盘
+flavor config unset language               # 从项目配置移除某一项
+flavor config list --json                  # 打印合并后的生效配置（脱敏）
+
+# 用量：汇总当前会话的 token 与缓存命中
+flavor usage                               # 人类可读的缓存命中表
+flavor usage --json                        # 机器可读的用量摘要
+```
+
+`flavor sessions list/show`、`flavor config list/get`、`flavor usage` 均支持 `--json` 以便脚本消费。
+
 ### Electron 桌面端
 
 ```bash
@@ -299,7 +327,9 @@ Skill 是带有 YAML 头信息的 `SKILL.md`，放在 `.flavor/skills/<name>/`
 
 长期记忆会区分用户偏好、行为反馈、项目约定和外部引用。自动提取只保存高置信候选，并提供确认、忽略和删除入口；密钥、Token、原始工具输出和模型猜测会被拒绝。
 
-图片提示支持 PNG、JPEG 和 WebP，单图最大 5 MiB、每次最多 5 张。桌面端支持选择或拖放；CLI 剪贴板图片目前支持 Windows 和 macOS。
+图片提示支持 PNG、JPEG 和 WebP，单图最大 5 MiB、每次最多 5 张。桌面端支持选择或拖放；CLI 剪贴板图片目前支持 Windows 和 macOS。CLI 标准粘贴会优先使用剪贴板文字，只有没有可用文字时才把剪贴板图像添加为附件；剪贴板同时含有文字和图片但需要图片时，使用 `/paste-image`。
+
+CLI 工具回执默认折叠，长会话只保留与终端视口成比例的回合与输出项窗口。在 Windows、Linux 和 macOS 上均使用 `Ctrl+O` 展开：渲染上限随之解除，更早的回合、被隐藏的输出项与完整工具明细都会显示，文本也不再截断；再按一次回到紧凑的响应式视图。macOS 的 `Command+O` 继续保留给终端或宿主应用。
 
 ## 权限与沙箱