Skip to content

Point 使用指南

Point 由两层组成：CLI 通过 Git 保存、恢复和发布 Point；Skill 读取 Agent 当前可见的 Session，并把这些动作放进自然的开发对话里。

用户只需要决定三件事：什么时候保存一个继续边界，什么时候把它锚定到 Git Commit，什么时候让团队依赖这段上下文。

安装

Point 需要 Git 和 Python 3.9 或更高版本。

安装 CLI：

python3 -m pip install "git+https://github.com/guix4ever/point.git"
point --version

安装 Point Skill：

npx skills add guix4ever/point --skill point

增加 -g 可以在所有项目中使用：

npx skills add guix4ever/point --skill point -g

在对话中使用

安装 Skill 后，直接描述你要的结果：

把这个 Session 保存成 Point。
从项目当前上下文继续。
从这个历史 Point 开一个新方向。
同时参考这两个 Point，在 master 上继续。
提交这次项目变更，并保留引出它的 Session。
把 Git Branch 和上下文一起发布给团队。

不需要手写 Agent 名称、Session Token、父节点或临时文件。Skill 负责这些接入细节。

保存当前 Session

告诉 Agent：

把现在的 Session 存一下。

Skill 会导出从上一个 Point 边界之后新发生的全部参与者可见事件，再调用：

point stash --session-file session.jsonl

session.jsonl 按原始顺序保留 Agent 集成能够访问、且参与者允许保存的 Session 事件。下面只是其中一种事件表示：

{"id":"e1","type":"message","role":"user","content":"重试次数必须有上限。"}
{"id":"e2","type":"message","role":"assistant","content":"我先检查当前失败路径。"}
{"id":"e3","type":"tool_call","call_id":"t1","name":"test","arguments":{"target":"retry"}}
{"id":"e4","type":"tool_result","call_id":"t1","name":"test","content":"passed"}

这是一种 Agent 与 CLI 之间的开放格式，通常不需要人手工编写。

第一次保存会创建 Point master。Point 默认只存在于当前 Clone，同一仓库里的其他本地 Agent 可以读取，团队远端暂时不可见。

从当前上下文继续

point resume

不带 ID 时，Point 从 master 继续。它会：

  1. 沿父节点遍历完整 DAG；
  2. 从旧到新返回每个可达 Session；
  3. 对共同祖先只读取一次；
  4. 将 master Tip 记为下一次保存的父 Point；
  5. 从此处开始记录新的 Session 事件。

下一次保存不会把刚刚恢复的历史复制进新 Point。完整现场通过父引用仍然可达。

Resume 只改变上下文来源，不切换 Git Branch、不修改工作区、不改写旧 Point，也不会自动发布。

查看或回到历史

point list
point show <point-id> --full
point resume <point-id>

show 只查看。Resume 精确历史 ID 时默认进入 detached 状态，不会意外推进 master。

如果这个方向需要长期存在，再给它一个 Point Branch：

point resume <point-id> --branch experiment

多 Agent 并行与汇聚

两个 Agent 可以从同一个 Point 形成不同方向：

point resume <origin> --branch bounded-backoff
point resume <origin> --branch circuit-breaker

第三个 Agent 可以同时读取两个结果：

point resume <point-a> <point-b> --branch master

新 Session 中真正发生的比较、验证和决定形成新的多父 Point。父节点表达来源，不执行自然语言 Merge，也不会把两个旧 Session 复制到新节点。

将 Session 与 Git Commit 连接

每个 Clone 安装一次可选 Hook：

point hooks install
point hooks status

Agent 提交项目变更时，Skill 会：

  1. 暂存确定要提交的项目变更；
  2. 准备本次新增的真实 Session 事件；
  3. 执行正常的 git commit；
  4. 由 post-commit Hook 创建 Commit Point；
  5. 在 Point 中记录刚产生的 Git Commit ID。

准备内容会绑定提交前的 Git HEAD 和暂存区 Tree，旧 Session 不会误连到后来的变更。没有准备真实 Session 时，Hook 什么也不创建，不会生成占位上下文。

如果仓库已有自定义 post-commit Hook，Point 不会覆盖它。可以在现有 Hook 中接入 point _post-commit。

发布团队上下文

point push master --remote origin

Push 会发布 master、它指向的不可变 Point，以及恢复它所需的全部父节点。无关的本地想法和实验分支不会被带上。

Git Branch 和上下文需要同时发布时：

point push master --remote origin --with-code

这是一次原子 Git Push：远端要么同时收到 Git Branch 与 Point 链路，要么都不接收。

另一位成员在新 Clone 中运行：

point fetch --remote origin
point resume

他得到的是原始 Session 工作现场，而不是事后整理出来的摘要。

什么时候保存

适合保存 Point 的时刻：

  • 一段意图已经足以交给另一位参与者继续；
  • 工作需要暂停，但项目变更还没有形成 Git Commit；
  • 需要让另一个 Agent 从这里独立探索；
  • 两个方向已经准备好进入新的判断 Session。

不需要每条消息都保存。Point 是有意义的继续边界，不是新的流水日志。

命令速查

命令 作用
point stash 保存新增 Session 事件为 Local Stash Point
point list 查看仓库中的 Point
point show <id> --full 查看 Point 及其 Session，不改变关系
point resume 从当前 master 恢复完整可达上下文
point resume <id> [<id>...] --branch <name> 从一个或多个来源继续
point branch 查看或创建 Point Branch
point push master 发布当前认可的上下文及父级链路
point fetch 获取团队发布的 Point
point hooks install 安装 Git Commit 关联 Hook
point hooks status 查看 Hook 状态