Agent Continuity · 0.3.0

TypeScript + Commander.js + Clack + Vite 的多 Agent 本地任务连续性工具；项目使用 pnpm 管理依赖与脚本。 一个 npm 包，通过 scope 选择用户级/项目级，通过 agent 选择适配器。

源码候选版：本轮新增请求账本、覆盖版本核对、结项证据校验与有界结束纠偏。原始离线验证见 docs/VALIDATION.md；现已生成 pnpm 锁文件，并在 macOS Node 24 + pnpm 10.30.2 下完成 pnpm verify。Clack 实机交互和各 Agent 实机验收仍未完成。

设计原则

用户消息事件 → TypeScript 适配器 → SQLite 请求账本与事件原子提交 → 派生 JSON/Markdown → 恢复输出。工具日志不再是最新要求的唯一载体。 断点的创建、事件保存不需要 LLM 主动调用工具。语义上的「下一步做什么」不由普通脚本猜测；可显式保存带请求版本的 progress。兼容字段 semanticSummary 仍为 null。

记录了事实 ≠ 已正确总结任务 ≠ 宿主保证在压缩后注入 ≠ 模型保证采用该信息。 各能力单独报告，不用一个笼统的「支持」覆盖所有 Agent。

0.3.0：防止旧完成态覆盖新要求

完整设计见 REQUEST-CONTINUITY.md，固定复现见 pnpm test:incident。

• 请求版本与事件序号分离：每条真实收到的用户输入分配 requestVersion；不靠 LLM 判断是否“值得记住”。
• 最新要求独立持久化并优先恢复，最近 24/10 条日志的滚动窗口不再决定它是否存在。
• 旧提交/旧包只能成为 baseline；新要求到来立即使旧完成态不再覆盖当前版本。
• Stop、SessionEnd、已生成恢复输出都不是业务完成证据。
• complete 使用 --request-version 做当前版本 CAS；拒绝旧版本以及旧工具调用晚到的结果。
• completed 要求 implementation/validation/delivery 三类当前版本证据；validation 必须观察到退出码 0。检查不了代码是否真的符合业务意图，不能把这些程序约束称为语义正确性证明。
• SQLite 先提交；写派生文件失败不会撤回已接收的新要求。

建议在隔离项目启用保护

pnpm start install --scope project --root /absolute/project --agent codex,claude \
  --capture metadata --request-capture redacted \
  --stop-guard once --ingress-failure block --dry-run
# 审阅上面的配置差异后，把 --dry-run 换成 --yes。

用户级改用 --scope user 并省略安装时的 --root。--agent all 仍可选择全部适配器，但不能据此假定它们均能阻止请求或在压缩后立即恢复。

| 参数 | 默认 | 含义 | |---|---|---| | --request-capture metadata/redacted | 首次继承 capture；升级保留已有值 | 单独控制要求正文。不存正文也会记录版本与缺口，但无法恢复全文 | | --stop-guard observe/once | observe | 最多一次有界纠偏；OpenCode 本版仅观察 | | --ingress-failure warn/block | warn | 入账失败时告警，或在支持的宿主拒绝本次要求；Hook 未加载/未运行时无法强制 |

redacted 仅是启发式脱敏，可能保留敏感信息；用户要求上限 32,768 字符，附件不复制。截断、缺失、旧格式来源均标记待核对，不冒充完整需求。已有隐私设置不会被静默扩大。

# 必须填写实际 root/task；这些命令从数据库读取，而不是相信编辑过的 Markdown。
pnpm start tasks --scope project --root /absolute/project
pnpm start requests --scope project --root /absolute/project --task TASK_ID --after 0
pnpm start export --scope project --root /absolute/project --task TASK_ID --json

# examples 是声明结构示例；version / eventSeq 必须换成真实当前值，不能原样拿来作证。
pnpm start checkpoint --scope project --root /absolute/project --task TASK_ID \
  --request-version 2 --manifest examples/progress.json --yes
pnpm start complete --scope project --root /absolute/project --task TASK_ID \
  --request-version 2 --manifest examples/completion.json --yes

--version / -v 仍是程序版本查询；任务版本明确叫 --request-version，避免 Commander 提前退出而绕过结项逻辑。 complete 支持 completed/answered/awaiting_user/cancelled；等待用户不是完成，取消也不是验收成功。普通问答建议 observe，不要为满足门禁制造无意义测试或假证据。

技术栈

| 部分 | 实现 | |---|---| | 源码、测试、发布脚本、构建配置 | TypeScript（strict） | | 打包 | Vite 8.2 的 Node-targeted library 多入口构建 | | TUI | @clack/prompts 1.x，使用成品 select/multiselect/text/confirm/spinner | | CLI / Hook / 发布配置参数 | Commander.js 13.1.0：子命令、选项校验、自动帮助、统一错误处理 | | 包管理 | pnpm 10.30.2，由 packageManager 固定；CI 使用 frozen-lockfile | | 存储 | Node 内置 node:sqlite，事务/WAL；不用 Python、pip、better-sqlite3 | | 运行要求 | Node >=22.16.0；本地 macOS/Linux |

Node 22 的 SQLite API 仍带实验性标记；本项目以已实现的 API 子集为基线，不称其为稳定数据库驱动。 Windows/cloud/网页聊天的安装与持久化不在本版承诺范围。具体协议来源和限制见 docs/ADAPTERS.md。

开发与构建（统一 pnpm）

# 已安装 Corepack 时启用；已使用 pnpm 的环境可直接检查版本。
corepack enable
pnpm --version                 # 本仓库 packageManager 固定为 10.30.2

# 当前仓库已包含经 pnpm 10.30.2 生成的锁文件。
pnpm install --frozen-lockfile
# 仅在明确更新依赖时使用普通安装，并审阅随之变化的 pnpm-lock.yaml：
pnpm install --no-frozen-lockfile

pnpm verify
pnpm start                     # 运行真正的 Vite 构建产物，进入 Clack TUI

verify 依次执行包管理器检查、全项目 typecheck、源码测试、Vite build、构建产物 smoke。 pnpm dev --help 可以检查源码 CLI；源码入口不会假装拥有 Vite 构建产物，安装须使用 pnpm start。 不要生成或混用 npm / Yarn / Bun 锁文件。CI 与发布保护刻意拒绝没有锁文件的构建，而不是在 CI 中重新解析依赖。 pnpm-lock.yaml 由项目固定的 pnpm 10.30.2 联网解析生成；依赖变更后必须审阅并提交锁文件变化。 没有 Corepack/pnpm 的机器按 pnpm 官方安装文档先安装工具，项目内不回退为另一种包管理器。

常用脚本：

pnpm dev --help
pnpm dev install --help
pnpm typecheck
pnpm test
pnpm build
pnpm test:dist
pnpm verify

交互入口

直接运行 node dist/cli.js 使用 Clack TUI：操作 → 范围 → 项目目录 → 多选 Agent → 隐私模式 → 文件预览 → 确认。 默认为不写入；Ctrl+C/取消由 Clack 处理。

用户可以使用 npx @urionz/agent-continuity 或 pnpm dlx @urionz/agent-continuity。这是消费发布包的入口，不改变源码仓库统一使用 pnpm 的约定。

CLI

# 用户级：安装预览，不修改
pnpm start install --scope user --agent all --dry-run

# 安装选择的适配器；global 是当前 OS user 的别名
pnpm start install --scope global --agent codex,claude,cursor,gemini,copilot,opencode --yes

# 项目级：可以不是 Git 仓库；该项目仅接管所选 Agent
pnpm start install --scope project --root "$PWD" --agent claude,cursor --capture redacted --yes

# 检查仅报告本地配置差异，不假装已获得信任/经过真实宿主验收
pnpm start check --scope user --agent all --json
pnpm start agents

# 停用选中 Agent 的本版适配条目，保留历史数据和其他配置
pnpm start uninstall --scope user --agent claude --yes

# 查看当前作用域内、指定工作区的任务
pnpm start tasks --scope user --root "$PWD"
pnpm start export --scope user --root "$PWD" --task TASK_ID

# 不按最近文件猜测任务，明确绑定另一个 Agent 的真实会话 ID
pnpm start bind --scope user --root "$PWD" --agent codex --session REAL_SESSION_ID --task TASK_ID --yes

Commander 自动提供 --help、<command> --help、help <command>、--version 与 -v；doctor 是 check 的别名。--agent 支持逗号分隔、重复传入及 all，归一化后去重；无效选项会报错而非忽略。--dry-run 始终优先于 --yes。

当前 TUI 是中文；CLI 的帮助与日志主要为英文。旧版 --lang/--disable-legacy 参数不在本版提供。

安装与状态位置

用户级运行文件：~/.agent-continuity/runtime/。 用户级状态：~/.agent-continuity/v5/workspaces/<canonical-path-hash>/。 项目级运行文件：<root>/.agent/continuity-runtime/。 项目级状态：<root>/.agent/continuity-v5/。

运行文件脱离 npx 缓存，Node 使用安装时的绝对路径。如果升级 Node 后旧路径被删除，需要重新安装。 项目标记 .agent/continuity.json 对每个 Agent 分别指定 project/user/off，不会因为项目仅安装 Claude 就阻止用户级 Codex。 新会话独立建档；明确 task binding 才跨会话/跨 Agent 共享将来的事实。不同作用域的数据库不自动同步。

非 Git 项目若从多个子目录独立启动，建议做项目级安装以固定根目录。 拒绝把 home、文件系统根目录或多根工作区中随便一个目录猜作项目。

重要限制

• 这不是整套「虚拟机/浏览器进程」检查点，不能恢复工具进程或未保存的内部推理。
• 仅记录宿主交付的事件；缺失事件、后台/异步事件顺序、未暴露的工具均不能靠脚本补全。
• 事件来源未进行签名认证：模拟调用也能写入数据，不能据此伪称真实 Desktop 验收。
• 不自动重跑已记录命令、不修改工具权限。默认观察；显式启用 stop-guard=once 后，支持的宿主最多收到一次纠偏，不将耗尽重试预算当作完成。
• 所有修改先预览，配置备份；JSONC/损坏 JSON/未知 schema 拒绝猜测覆盖。
• 当前生成的是本机绝对路径配置，不能直接提交为可移植的团队/云端配置。
• 不自动迁移旧 v1–v4 数据，不自动关闭旧 Hook；升级须先停用旧插件并保留备份，见 docs/MIGRATION.md。
• 没有默认云同步、额外总结模型、遥测、远程 API 或自动全文聊天扫描。

开发结构

src/
  cli.ts                  # 可执行薄入口
  cli/program.ts          # Commander 子命令和 action
  cli/options.ts          # Agent 选项归一化
  version.ts              # package.json 单一版本来源
  hook.ts                 # stdin/stdout Hook 入口
  ui/wizard.ts            # Clack，仅组合库组件
  agents/registry.ts      # 6 个宿主能力、事件、配置位置
  agents/normalize.ts     # 不同字段与输出协议归一化
  agents/opencode-plugin.ts # OpenCode 原生插件 -> Node 进程桥接
  core/                   # 存储、恢复、隐私、路径校验
  install/                # 合并配置、安装计划、备份/回滚
scripts/                   # TypeScript 构建/发布/包管理器检查
package.json               # packageManager: [email protected]
.npmrc                     # pnpm/Node 版本约束
pnpm-lock.yaml             # pnpm 10.30.2 生成并提交，CI 使用 frozen-lockfile
vite.config.ts             # CLI / Hook / OpenCode 三个构建入口

增加 Agent 时先定义请求准入、事件、恢复及结束控制能力，随后补配置生成、输入输出样例测试和真实宿主验收。 不能仅添加一个名字就宣称全面兼容。MCP-only/无生命周期的客户端暂不虚报自动记录支持。