common-memory-core 0.2.0 → 0.2.1

package/docs/tui-workbench.md

@@ -1,173 +1,105 @@
 # Common Memory 交互工作台
 
-## 设计判断与调研依据
-
-统一的是用户的操作旅程，不是协议、宿主生命周期或授权来源。默认运行
-`common-memory` 打开一个持续运行、可以返回的任务工作台；自动化命令和协议
-入口继续存在。采用已有 Clack 的菜单、表单、分页查看，不引入全屏渲染框架、
-第二份业务实现或新的后台服务。
-
-本次调研核对了以下官方／项目一手文档，设计借鉴不等于性能实测：
-
-- [Command Line Interface Guidelines](https://clig.dev)：人类优先但保留组合能力；
-  仅在 TTY 提示；明确确认危险操作；取消不能伪装成功。
-- [Lazygit 导航](https://lazygit.dev/docs)及[项目快捷键](https://github.com/jesseduffield/lazygit/blob/master/docs/keybindings/Keybindings_en.md)：
-  以当前对象和任务组织操作，导航／上下文动作可发现。借鉴分区和逐层进入，
-  **不**照搬 Git 面板、快捷键数量或 Undo 能力。
-- [Clack Prompts](https://bomb.sh/docs/clack/packages/prompts)：沿用 select、
-  multiselect、text、password、confirm 和 cancel。API 与取消键同时核对了本地
-  已安装的 `@clack/prompts` 类型声明和 `@clack/core` 实现。
-- [Codex Hooks](https://learn.chatgpt.com/docs/hooks)：非托管 Hook 必须通过宿主
-  `/hooks` 检查和信任；多个来源的 Hook 可以同时运行，生成文件不等于启用。
-- [MCP stdio](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio)：
-  stdout 只能传协议消息，不能混入 TUI 提示。
-- Pi 官方安装包中的完整 `README.md`、`docs/packages.md`：本地 package 使用
-  `pi install <path>`／`pi remove <path>`；`pi list` 检查注册，`pi config` 管理资源。
-  工作台交给 Pi 自己执行这些命令，不实现另一套 Pi settings/trust 编辑器。
-
-阅读本仓库 `AGENTS.md`、README、[架构](03-target-architecture.md)、
-[会话接入](session-integration.md)和 CLI/MCP/Pi/宿主适配代码后，确认以下边界：
-Markdown 是事实来源；Runtime SQLite 是持久队列，不是可重建索引；TUI 不增加
-写权限、检索、跨项目读取、导入的用户证据地位或 MCP capabilities。
-
-## 原入口清单与归属
-
-| 原入口 | 性质 | 工作台位置／保留理由 |
-| --- | --- | --- |
-| 无参数 TUI：Status/API/Network | 人类入口 | 改为完整 Home 和六个任务分区 |
-| `config`、`config --network` | 人类表单快捷入口 | Settings；保留直接表单快捷方式，非 TTY 明确失败 |
-| `status`、`show` | 人类＋自动化 | Overview、Memory；保留脚本输出，查看走同一业务函数 |
-| `import` | 人类＋自动化 | Memory 导入向导；仍调用同一 Writer 入队／处理路径 |
-| `project register/list/remove` | 人类＋自动化 | Projects & permissions；CLI 参数和注册语义保留 |
-| `retry`、`flush` | 运维＋自动化 | Maintenance；保留脚本退出码、正常退避和租约行为 |
-| `network-test` | 显式诊断＋自动化 | Settings；用户确认后才发合成请求 |
-| `mcp-config` | 配置生成＋自动化 | Integrations 预览／导出；继续提供 stdout TOML |
-| `codex-config`、`work-config` | 配置生成＋自动化 | Integrations 预览／导出 bundle，CLI 继续支持无人值守生成 |
-| `mcp` | **机器协议** | 保留独立 stdio，固定 relay/init/read；不得显示 TUI |
-| `codex-hook`、`work-hook` | **宿主 Hook 协议** | 保留 JSON stdin/stdout、持久 inbox 和宿主身份 |
-| `session-drain` | **机器消费者**＋显式恢复 | 保留 detached 使用；工作台可前台启动同一入口并等待结果 |
-| `session-refresh` | **宿主身份相关操作** | 保留显式 Skill 命令；不能由 TUI 用 cwd 猜测活动会话 |
-| Pi Extension、`memory_read`、`/memory-flush`、`/memory-refresh` | **宿主生命周期／会话内交互** | 保留原生入口；外部工作台不能替换它们的会话上下文 |
-| Codex/Work 的 `/hooks`、宿主 MCP 设置 | **宿主所有的信任和启停** | 工作台提供安装／停用说明，不修改 trust store |
-| 本地 `config.json`、private `.env`、Canonical Markdown | 用户所有的文件 | 不隐藏、不迁移、不删除；设置表单复用配置验证和私有文件写入 |
-
-没有删除已有命令；CLI 和 TUI 是同一产品的两种操作方式。
-
-## 最终信息架构
+`common-memory` 在交互终端打开中文任务菜单。v0.2.1 参考本机 search-boost 的
+`lib/installer/tui.mjs`、`index.mjs`、`keys-wizard.mjs`，以及 CodeGraph v1.6.0 的
+`dist/installer/index.js`：首页先问用户要做什么；按当前任务询问必要参数；完成后
+指出下一步。不照搬它们的授权默认值或宿主配置写入方式。
+
+沿用已安装的 Clack select、multiselect、text、password、confirm 和分页查看，
+没有新增界面依赖、全屏渲染框架、后台服务或第二份业务实现。
+
+## 入口与操作路径
 
 ```text
-common-memory
-  Home（当前 model/API、dataRoot、导航提示；未配置时只提供配置和退出）
-  ├─ Overview
-  │   ├─ 配置／真实存储路径／密钥是否存在／网络选择（不是连通性结果）
-  │   └─ 队列摘要、刷新、转入维护
-  ├─ Memory
-  │   ├─ 选择 global／已注册项目 → 文档 → 分页查看
-  │   └─ Markdown 导入：文件、范围、作者、标签、处理方式 → 确认 → 结果
-  ├─ Projects & permissions
-  │   ├─ 注册、项目详情、只移除注册
-  │   └─ 独立选择 disclosure scopes、writable scopes、provenance
-  ├─ Integrations
-  │   ├─ 本地就绪条件（宿主状态明确标为未验证）
-  │   ├─ Pi：确认后交给 pi list/install/config/remove
-  │   ├─ Codex：会话 Hook + read MCP + 显式 refresh Skill bundle
-  │   ├─ ChatGPT Work：会话 Hook + 独立 read/init MCP + refresh Skill bundle
-  │   └─ MCP-only：独立 init/read 配置块预览／导出
-  ├─ Maintenance
-  │   ├─ 队列／job 诊断／dead job retry／无正文 session 摘要
-  │   ├─ flush：处理队列，不封未结束的会话尾批
-  │   └─ session-drain：恢复持久 handoff，等待正常租约／退避
-  └─ Settings
-      ├─ model、显式 API 模式、可选密钥更新
-      ├─ network、proxy、CA；单独确认的合成连通测试
-      ├─ 授权（复用同一表单）
-      └─ advanced：输出／thinking 参数、调度／cache／字节限制、切换 dataRoot
+未配置：开始设置 → API 地址、模型、接口、可选密钥 → 确认保存
+                   └─ 连接助手 / 测试模型 / 调整权限 / 返回首页
+
+首页：想做什么？
+  ├─ 查看记忆 → 个人 / 已登记项目 → 文档、文件位置
+  ├─ 导入 Markdown → 必要时引导授权 → 文件、范围、来源、处理方式 → 确认
+  ├─ 连接 / 管理 AI 助手
+  │   ├─ Pi → 交给 Pi 自己安装、查看、启停、移除
+  │   ├─ Codex / Work → 运行环境、项目、新目录 → 摘要、可选预览 → 生成
+  │   ├─ 其他 MCP 助手 → 环境、项目 → 配置预览、可选导出
+  │   └─ 检查本机接入条件（不检测助手是否已连接）
+  ├─ 项目与权限 → 添加项目、项目详情、移除登记、独立授权
+  ├─ 模型与设置
+  │   ├─ 更换模型 / API 地址
+  │   ├─ 单独设置 / 更换 API Key，或更换凭据环境变量
+  │   ├─ 代理 / 网络 / CA
+  │   ├─ 测试模型连接（确认后发送合成请求，不含记忆）
+  │   ├─ 权限
+  │   └─ 高级设置 → 输出、思考、处理节奏、容量、存储目录
+  ├─ 处理未完成任务 → 整理队列、失败诊断 / 重试、恢复交接、会话摘要
+  └─ 查看运行状态 → 本地进度、刷新、配置与存储路径详情
 ```
 
-高级参数在工作台内编辑受验证的 JSON 对象，不引入另一份参数 schema；切换
-API 会说明并清除不兼容的 thinking 参数，其他设置保留。切换 dataRoot 是
-**选择另一个 store**，不是迁移，需要先停止客户端；原 Markdown/SQLite 不动。
-
-上下键、Enter 和多选 Space 沿用 Clack；每个分区有 Back。表单 Esc/Ctrl+C
-返回当前分区，分区菜单取消返回 Home，Home 取消退出。操作失败留在分区内显示，
-不污染下一次操作的退出码。只在 stdin 和 stdout 都是 TTY 时打开界面；无参数
-非 TTY 输出入口说明并退出，直接配置表单非 TTY 报错，不等待输入。
-
-文档查看是同一次授权读取的分页快照，重新打开 Browse 获取新内容；没有检索、
-排名、跨项目汇总或直接编辑 Canonical 的新接口。终端控制字符可见转义，只影响
-TUI 呈现，原 Markdown 和消费者／CLI 原文不变。状态只显示计数、ID 和受控诊断，
-不打印用户、assistant/tool、inbox 正文。现有 Runtime 存在时状态路径仍通过
-RuntimeStore 打开，可能执行其已有幂等 schema 初始化；不是全新的数据库只读模式。
-Runtime 不存在时不创建它。MCP read-only 进程的“从不开 Runtime”边界不变。
-
-## Integration management 的界限
-
-生成前必须自行选择宿主运行环境（同一 POSIX 或 Windows→WSL），不能仅根据
-`WSL_DISTRO_NAME` 推测桌面进程在哪里。可选项目来自本地 registry，未授权项目有
-明确提示，生成过程不自动添加授权。配置、Skill 和可选 PowerShell bridge 均可
-分页预览；确认后才写文件，不携带 API key 或代理秘密。
-
-工作台 bundle 选择新目录；自动化生成器仍兼容已有目录，但先检查所有目标文件
-是否冲突、bundle 内目录是否为 symlink，再开始写文件，使用独占创建，不覆盖
-旧文件。检查到后面的 Skill 文件冲突也不会先写前面的 TOML。磁盘中途失败可能
-留下部分新 bundle，需要检查错误并使用新目录重试，不假装全部成功。
-
-Codex/Work/MCP 的宿主配置合并、Hook 信任、MCP 启停仍由宿主所有者完成。
-工作台提供步骤和移除说明，没有通用宿主配置自动编辑器，也不写信任 store。
-Pi 可以从工作台确认后调用 PATH 上的官方 `pi` 管理命令，使用 argument array、
-继承终端并固定当前 COMMON_MEMORY_HOME，不拼 shell 命令。成功退出只证明该
-Pi 命令结束，不证明扩展正在捕获或真实模型已读到记忆。
-
-session-refresh 必须来自实际宿主实例＋thread，继续在会话内执行。
-session-drain 的工作台动作前台启动原机器入口；Ctrl+C 停止该 consumer，持久
-未完成工作留待恢复。flush/import/network-test 在进程内复用既有操作，取消信号
-传给对应模型请求。保存配置不执行网络测试、不热更新／热撤销现存客户端。
-
-## 关键解耦
-
-- `src/cli/operations.ts`：共享状态快照、授权读取、项目注册／移除、retry；
-  `main.ts` 和 TUI 都调用这些函数，没有各自一份 SQL／权限选择／锁实现。
-- `tui-settings.ts`：配置表单、状态格式；保留可选 sessionCache、旧 proxy 字段缺省、
-  未修改的密钥和 CA。保存前检查配置是否被外部编辑，防止长时间表单覆盖已观察到
-  的新版本；这不是多个配置文件的原子事务或完整的并发锁协议。
-- `tui-prompts.ts`：TTY、返回／取消、错误隔离、终端文本和分页呈现。
-- `tui-integrations.ts`：宿主工作流和就绪说明；生成内容仍来自原 generator。
-- `work-config.ts`：准备／渲染与写 bundle 分开，CLI 和 TUI 共用，预览没有文件写入。
-- `interactive-process.ts`：有界的原生宿主／消费者命令交接，不调用 shell。
-- import/flush 使用原函数；network-test 加可注入日志和取消信号，仍不打开 SQLite。
-
-没有修改 Core、Writer 决策协议、scope/provenance 映射、MCP 或 Pi capture 代码。
-配置保存仍由现有 validator 和 private file writer 完成。secret 和 JSON 是两个
-独立私有文件，不承诺它们跨文件提交的原子性。
-
-## 验证与剩余限制
-
-测试入口：
-
-- `tests/cli/tui.test.ts`：真实业务配置／文件＋脚本化 prompt 驱动导航，覆盖取消、
-  错误、授权分离、导入/flush/probe/recovery 路由、配置保留、终端转义和 Pi 交接。
-- `tests/cli/workbench-entries.test.ts`：真实子进程非 TTY/CLI、机器错误通道、
-  scope 隔离、无正文 job/session 状态、bundle 冲突／symlink 和共享生成结果。
-- `tests/cli/network-test.test.ts`：合成 probe 输出、取消信号和连接／监听器清理。
-- 既有 import、MCP、Pi、Codex/Work、session-drain 测试继续覆盖下层真实路径。
-
-完整 gate 使用 Node 24.x：`node scripts/verify.mjs`；构建后追加
-`npm run test:consumer`。无需个人记忆、真实模型或生产集成设置。
-
-本次结果（Node 24.20.0）：
-
-- 完整 gate 通过：typecheck、63 个源文件边界检查、35 个测试文件／425 项测试、build。
-- tarball consumer 通过：typed consumer、维护 prompt asset、Writer、Pi load、CLI startup。
-- 构建产物的真实 Linux PTY 冒烟通过：Home→Overview→Memory、授权文档分页、
-  终端 resize、逐层 Esc 返回和正常退出；确认未创建 SQLite、未改变 Markdown。
-- `git diff --check` 通过。没有调用真实模型，也没有安装／修改用户生产宿主配置。
-- 首次全量 gate 暴露了预览测试的分页断言错误，已修正；另一个既有网络测试依赖
-  `.invalid` 必然 DNS 失败，但此环境实测解析成 `198.18.0.87`。测试改为受控
-  `dns.lookup` 返回 ENOTFOUND，仍经过真实 NetworkClient 的错误处理；生产网络
-  代码未因该测试改变。复验全部通过。现有 TLS-IP 弃用和 SOCKS5 实验性警告仍存在。
-
-尚未覆盖：真实 Desktop UI 的信任、宿主配置合并后的端到端启用；本次 Linux
-终端检查不证明 Windows/macOS 真机体验或 CI。宿主安装和存活状态不做猜测，
-必须在宿主核验。不存在统一的一键暂停所有消费者／撤销已披露记忆的能力。
-已损坏或不支持版本的配置仍 fail closed，需要先在文件中修复；没有静默重置或
-迁移。高级参数仍是受校验 JSON 表单，不是每个参数独立控件。
+首次设置不再要求填写环境变量名和存储路径，沿用默认值；后续分别在密钥和高级
+设置中修改。保存后提供可选的后续步骤，不自动调用模型或启动助手。默认只授权
+个人记忆和用户表达，其他材料与项目仍需明确授权。
+
+高级设置不再要求编辑 JSON。每次修改一项，显示当前值与新值，确认后调用原配置
+验证器保存。输出长度可留空恢复接口默认；思考选项按 Responses / Chat 区分，
+切换互斥参数时清除旧项；会话暂存可恢复内置默认值。其他配置及私有秘密保持不变。
+
+## 导航与结果反馈
+
+- 上下键选择、Enter 确认、多选 Space；每个分区有明确返回选项。
+- 表单 Esc/Ctrl+C 取消当前操作；分区菜单取消回到调用它的菜单；首页取消退出。
+  高级设置的返回回到设置分区。首页记住刚才使用的入口。
+- 保存、授权、导入、模型请求、重试、导出与宿主命令均有明确确认，默认不执行。
+  取消后续步骤不撤回已经保存的设置或已经排队的材料，不承诺 Undo。
+- 首页不展开路径、队列、授权术语或多段说明；只有显式查看状态才打开已有 Runtime。
+- 空记忆说明如何开始；导入缺权限时提供打开权限表单的入口，不自动增加授权。
+  授权保存后重新读取配置，仍未允许导入时不入队。
+- 导入结果区分排队、处理完成和实际保留；失败给出检查入口，不将等待或取消当成功。
+- Codex/Work 先显示将生成什么、写到哪里；技术配置、Skill、桥接可按需分页预览，
+  不再要求逐个读完才能生成。生成后明确说明如何在实际助手中安装和启用。
+
+## 保持的边界
+
+Canonical Markdown 是事实来源；SQLite 是持久队列、租约与来源存储，不是可重建
+索引。TUI 使用 `operations.ts`、现有 import/flush/network-test、配置验证器和
+接入生成器，不增加 Core 写权限、检索、跨项目读取或宿主信任能力。
+
+读取使用与消费者相同的授权范围：个人记忆加所选已登记项目，与授权范围取交集。
+文档是本次读取的分页快照，重新打开「查看记忆」刷新。可以查看文件目录，在自己的
+编辑器中修改 Markdown；界面不新增写入接口。终端控制字符可见转义，原文不变。
+
+项目登记、允许读取/发送、允许写入、允许发送的材料类型分别处理。AI 理解和导入
+文档始终保留来源，不成为用户声明，不能单独作为遗忘用户来源内容的依据。
+更改授权不热撤销已运行客户端，需要重启。长时间表单保存前比较配置是否已变化，
+按对象内容比较，不把 JSON 键顺序变化误判为并发编辑；这不是跨文件原子事务或锁。
+
+切换存储是选择另一份 store，不复制、合并或删除旧数据；先停写端，切换后重新生成
+受影响的接入文件。密钥和配置是独立私有文件，不承诺跨文件提交原子性。
+
+Runtime 不存在时查看状态不创建它。已存在时沿用 RuntimeStore 的打开路径，可能
+执行已有的幂等 schema 初始化，不宣称数据库只读模式。记忆读取与 MCP read 仍不打开
+SQLite。会话摘要只显示 ID、计数和交接状态；任务诊断不含聊天正文或模型响应正文。
+
+Pi 的 package/settings/trust 交给 PATH 中的官方 `pi` 命令，采用参数数组、继承终端
+并固定当前 COMMON_MEMORY_HOME，不拼接 shell。不推测真实宿主是否已经捕获或读取。
+Codex/Work/MCP 只生成或导出配置，不修改宿主信任。WSL 环境不用于猜测助手运行位置。
+新 bundle 目录和导出文件不覆盖已有目标，底层写入失败可能留下部分新文件。
+
+`/memory-refresh` 和 Pi 原生命令仍属于实际会话；TUI 不用 cwd 猜测会话身份。
+恢复交接前台运行同一 `session-drain` 入口；Ctrl+C 停止当前消费者，持久工作可恢复。
+flush 不封正在进行的会话尾批；完整十次交互或实际退出才交接。
+
+自动化 CLI、stdio MCP、JSON Hook 和 detached 消费者入口不变。非 TTY 不打开菜单；
+直接配置表单明确报错。损坏配置不静默重置。CLI 技术状态输出不因中文界面改动而改变。
+
+## 验证入口
+
+- `tests/cli/tui.test.ts`：脚本化 prompt + 临时真实配置/文件，覆盖导航、取消、首页
+  焦点、首次引导、独立密钥、导入授权、逐项高级设置、存储不迁移和接入导出。
+- `tests/cli/workbench-entries.test.ts`：非 TTY/CLI、协议错误通道、范围隔离、无正文
+  诊断、bundle 冲突/符号链接和生成结果一致性。
+- `tests/cli/network-test.test.ts`：合成连接测试、取消、清理。
+- `node scripts/verify.mjs`：Node 24.x 下类型、边界、全量测试和构建。
+- `npm run test:consumer` / `npm run test:published`：隔离安装的本地/registry 包验证。
+
+真实终端体验需另做 PTY 检查；脚本化 prompt 测试不证明终端显示效果。Linux 检查不
+替代 macOS/Windows CI、真实 Desktop UI 信任流程或真实模型质量验证。历史验证记录
+不能作为本次版本通过的证据。发布与平台边界见 [releasing.md](releasing.md)。

package/docs/usage.md

@@ -165,16 +165,23 @@ Research, explicit environment limits and acceptance evidence:
 
 ## Interactive workbench
 
-Run **`common-memory`** in a terminal. Home leads to:
+Run **`common-memory`** in a terminal. The Chinese task menu leads to:
 
-| Area | Tasks |
+| Menu | Tasks |
 | --- | --- |
-| Overview | Configuration, actual storage paths, network selection and queue health; refresh locally |
-| Memory | Browse authorized consumer documents with pagination; import local Markdown with explicit confirmation |
-| Projects & permissions | Register/view/remove projects; independently manage disclosure, write scopes and provenance |
-| Integrations | Local readiness; Pi's official package/resource manager; Codex/Work bundle preview/export; MCP configuration preview/export |
-| Maintenance | Job diagnostics and dead-job retry; session summaries without bodies; flush and durable handoff recovery |
-| Settings | Model/API/credentials, network/CA, explicit synthetic connection test, advanced tuning/limits/storage |
+| 查看记忆 | Browse authorized documents with pagination; locate the Markdown files |
+| 导入 Markdown | Import local Markdown; offer an explicit permission form if needed, never auto-grant |
+| 连接 / 管理 AI 助手 | Pi's own manager; Codex/Work export summary and optional technical previews; MCP preview/export |
+| 项目与权限 | Register/view/remove projects; independently manage reads, writes and material types |
+| 模型与设置 | Model/API, independent key rotation, network/CA, synthetic connection test, individual advanced settings |
+| 处理未完成任务 | Job diagnostics and retry; readable session summaries; queue processing and handoff recovery |
+| 查看运行状态 | Local queue health; optional configuration and actual storage-path details |
+
+First-time setup asks for the API address, model, API type and optional key, then offers
+connection, permission and test steps that can be skipped. Advanced settings use menus
+and numeric fields rather than JSON editing; each confirmed edit preserves unrelated
+settings. The home menu remembers the last action. Saving a step is not undone by
+cancelling a later step.
 
 Use arrows and Enter, Space for multi-select, and Back to return. Esc/Ctrl+C cancels a
 form; cancellation at Home exits. Pending work remains durable. No model call is made

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "common-memory-core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "MIT",
   "description": "User-owned Markdown memory with durable maintenance, Pi integration and local stdio MCP access.",
   "repository": {
@@ -56,7 +56,7 @@
     "test:fixtures": "vitest run tests/v2",
     "test:recovery": "vitest run tests/v2",
     "test:consumer": "node scripts/consumer-smoke.mjs",
-    "test:published": "node scripts/consumer-smoke.mjs --registry-version 0.2.0",
+    "test:published": "node scripts/consumer-smoke.mjs --registry-version 0.2.1",
     "test:remote-contract": "vitest run tests/memory-manager",
     "prepack": "npm run build",
     "release:check": "node scripts/check-release.mjs",