# https://github.com/0spoon/seamless 项目说明书

生成时间：2026-07-21 16:47:46 UTC

## 目录

- [系统总览、架构与构建流程](#page-1)
- [记忆、笔记、检索与归属](#page-2)
- [任务协调、计划、试验与 Gardener 策展](#page-3)
- [Console、MCP、Hooks 与跨平台部署运维](#page-4)

<a id='page-1'></a>

## 系统总览、架构与构建流程

### 相关页面

相关主题：[记忆、笔记、检索与归属](#page-2), [任务协调、计划、试验与 Gardener 策展](#page-3), [Console、MCP、Hooks 与跨平台部署运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/0spoon/seamless/blob/main/README.md)
- [Makefile](https://github.com/0spoon/seamless/blob/main/Makefile)
- [go.mod](https://github.com/0spoon/seamless/blob/main/go.mod)
- [cmd/seamlessd/main.go](https://github.com/0spoon/seamless/blob/main/cmd/seamlessd/main.go)
- [cmd/seam/main.go](https://github.com/0spoon/seamless/blob/main/cmd/seam/main.go)
- [cmd/docsgen/main.go](https://github.com/0spoon/seamless/blob/main/cmd/docsgen/main.go)
- [scripts/install.sh](https://github.com/0spoon/seamless/blob/main/scripts/install.sh)
- [internal/daemon/daemon.go](https://github.com/0spoon/seamless/blob/main/internal/daemon/daemon.go)
- [internal/hooks/hooks.go](https://github.com/0spoon/seamless/blob/main/internal/hooks/hooks.go)
- [console/](https://github.com/0spoon/seamless/tree/main/console)
</details>

# 系统总览、架构与构建流程

## 一、项目定位与组成

`seamless` 是一个面向多 AI 编码代理（Claude Code、Codex 等）的会话捕获、归因与可视化平台。它通过 hook 生命周期钩子拦截客户端事件，把会话、笔记、记忆、任务、计划与实验记录聚合到本地守护进程 `seamlessd`，再由 Web Console 提供统一的"库（Library）"视图进行回看与编辑。资料来源：[README.md:1-30]()

仓库在物理形态上由三块构成：

| 模块 | 路径 | 职责 |
|------|------|------|
| 守护进程 | `cmd/seamlessd`、`internal/daemon` | 跨 OS 服务注册、捕获 URL、客户端 hook 编排 |
| CLI 工具 | `cmd/seam` | 面向用户的 `family`、`hook`、`update`、`install` 等子命令 |
| Web Console | `console/` | 库布局、Settings、re 卡（reach card）等前端界面 |

`cmd/docsgen` 负责从源码注释生成文档，避免手写 API 引用造成的漂移。资料来源：[cmd/docsgen/main.go:1-40]()

## 二、进程与数据流架构

运行时由两个常驻 Go 二进制与一个浏览器端 SPA 组成：

```mermaid
flowchart LR
    CC[Claude Code] -- hook JSON --> SEAMD[seam CLI / hook]
    CX[Codex] -- hook JSON --> SEAMD
    SEAMD -- HTTP --> DAEMON[seamlessd 守护进程]
    DAEMON -- SQLite / FS --> STORE[(本地存储)]
    DAEMON -- REST --> CONSOLE[Web Console]
    CONSOLE -- 浏览器 --> USER[用户]
```

`seam` CLI 在被客户端 hook 触发时仅做轻量转译（v0.3.2 起支持 exec-form 命令 hook），核心写入逻辑全部落在 `seamlessd` 中。守护进程统一负责：会话编排、`capture_url` 端口白名单（v0.3.0）、MCP stdio↔HTTP 代理（v0.3.3）、briefing 自动注入（v0.3.0 可在 Settings 中编辑），以及归因字段（harness、model，v0.3.7）。资料来源：[cmd/seam/main.go:1-60]() [internal/hooks/hooks.go:1-80]() [internal/daemon/daemon.go:1-100]()

前端 Console 从 v0.3.6 起把 Notes、Memories、Tasks 合并为统一的 Library 布局，v0.3.9 又新增 Labs 与 Trials 屏幕、读者导航条以及共享的 library chrome，使所有内容类型的渲染管线一致。资料来源：[README.md:60-90]()

## 三、构建与发布流程

仓库根目录的 `Makefile` 是唯一的构建入口，所有跨 OS 脚本均通过它派发。常用目标包括：

- `make build`：调用 `go build` 同时产出 `seamlessd` 与 `seam` 二进制
- `make test`：运行 Go 单元测试；v0.3.8 移除了 fake-codex 测试中对负载敏感的 5 秒截止
- `make install` / `make uninstall`：跨 OS 安装与卸载（v0.3.5 新增 `seamlessd uninstall`）
- `make update` / `seamlessd update --check`：v0.3.6 引入的更新自检能力

`go.mod` 锁定 Go 工具链与第三方依赖，守护进程与 CLI 共用同一 module，避免重复依赖解析。资料来源：[Makefile:1-80]() [go.mod:1-20]()

发布流程采用语义化版本与 GitHub Releases：每个 tag（如 v0.3.9）对应一份 Changelog，commit 前缀遵循 Conventional Commits（`feat:`、`fix:`、`chore:`），使得 `cmd/docsgen` 与社区引用都能稳定定位提交。Windows 打包在 v0.3.2 引入，由 `Makefile` 的 windows 目标驱动 installer 与监督脚本。资料来源：[Makefile:80-140]()

## 四、跨 OS 部署与升级

`seamlessd` 在 Linux/macOS 上以 systemd 或 launchd 单元注册，在 Windows 上以服务形式注册（v0.3.2），并通过 `start|stop|restart|status` 子命令（v0.3.5）对外暴露一致接口。安装脚本 `scripts/install.sh` 提供交互式客户端选择器（v0.3.4），并在输出上做了结构化、彩色化、精简化处理（v0.3.4）。v0.3.8 进一步去掉了对 Claude Code 的静默回退，要求用户显式确认客户端。资料来源：[scripts/install.sh:1-60]() [internal/daemon/daemon.go:100-160]()

升级路径方面，`seamlessd update` 与 `seamlessd update --check` 与 `make update` 行为一致（v0.3.6），避免 CLI 与 Makefile 行为分叉。Console 端 `capture_url` 端口白名单与项目族（family）编辑均在 Settings 页面可调，使运维策略不再依赖源码改动。资料来源：[cmd/seamlessd/main.go:1-80]() [README.md:90-130]()

> 总结：`seamless` 通过 `seam` 钩子 + `seamlessd` 守护 + Web Console 三层结构，把多代理会话转化为可检索、可归因、可编辑的本地知识库；`Makefile` + Conventional Commits + GitHub Releases 共同构成可重复的构建与发布链路。

---

<a id='page-2'></a>

## 记忆、笔记、检索与归属

### 相关页面

相关主题：[系统总览、架构与构建流程](#page-1), [任务协调、计划、试验与 Gardener 策展](#page-3), [Console、MCP、Hooks 与跨平台部署运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [internal/files/files.go](https://github.com/0spoon/seamless/blob/main/internal/files/files.go)
- [internal/files/manager.go](https://github.com/0spoon/seamless/blob/main/internal/files/manager.go)
- [internal/files/frontmatter.go](https://github.com/0spoon/seamless/blob/main/internal/files/frontmatter.go)
- [internal/store/memories.go](https://github.com/0spoon/seamless/blob/main/internal/store/memories.go)
- [internal/store/notes.go](https://github.com/0spoon/seamless/blob/main/internal/store/notes.go)
- [internal/store/embeddings.go](https://github.com/0spoon/seamless/blob/main/internal/store/embeddings.go)
- [internal/store/attribution.go](https://github.com/0spoon/seamless/blob/main/internal/store/attribution.go)
- [internal/store/sessions.go](https://github.com/0spoon/seamless/blob/main/internal/store/sessions.go)
- [internal/briefing/briefing.go](https://github.com/0spoon/seamless/blob/main/internal/briefing/briefing.go)
- [internal/console/library.go](https://github.com/0spoon/seamless/blob/main/internal/console/library.go)
</details>

# 记忆、笔记、检索与归属

## 概述：共享知识层的角色与作用域

Seamless 把"会话 → 记忆 / 笔记 → 下次会话"作为一条跨模型、跨客户端的共享知识链路。其核心职责有三：

1. **沉淀**：在代理会话进行中，把高价值的片段固化为持久化的 `memory` 或 `note`。
2. **检索**：在新的会话启动或显式请求时，按当前上下文的相关性回注（briefing）。
3. **归属**：记录每条记忆 / 笔记 / 会话来自哪个 harness 与 model，从而在跨客户端切换时保持可追溯。

这层能力从 v0.3.5 起跨 Windows / macOS / Linux 一致工作，由 `seamlessd` 服务统一托管；用户通过 Console 的 Library 视图统一访问。v0.3.6 把 Notes、Memories、Tasks 合并到同一个 library 布局，v0.3.9 又加入 Labs 与 Trials 两个新的 library 屏幕，使得记忆与笔记成为控制台内一等公民。

资料来源：[internal/store/memories.go:1-40]()、[internal/store/notes.go:1-30]()、[internal/console/library.go:1-60]()

## 存储与元数据：本地文件 + YAML frontmatter

记忆与笔记采用统一的本地文件存储策略：每条记录是一个独立 Markdown 文件，正文为内容主体，元数据以 YAML frontmatter 形式落在文件顶部。这种"文件即记录"的形态让用户能够直接用编辑器审阅、批量改写、纳入版本控制。

| 维度 | 记忆 (memory) | 笔记 (note) |
|------|-------------|-----------|
| 主要来源 | 自动从会话中提炼 | 用户或代理显式编写 |
| 元数据关键字段 | created_at、family、source_session_id、embedding_ref | created_at、family、task_ref、embedding_ref |
| 写入入口 | stop-hook / tail-harvest | hook、Console 编辑器 |
| 读取入口 | briefing、Library 视图 | Library 视图、briefing |

frontmatter 解析与构造集中在 `internal/files/frontmatter.go`，所有写盘动作统一经过 `internal/files/manager.go` 的目录枚举与 family 分组，使得 family 维度的批量编辑（例如 v0.3.9 在 Settings 中编辑 project families）无需逐条操作。

资料来源：[internal/files/files.go:1-80]()、[internal/files/manager.go:1-60]()、[internal/files/frontmatter.go:1-120]()、[internal/store/memories.go:80-160]()、[internal/store/notes.go:60-140]()

## 检索与简报：基于嵌入的上下文回注

检索层由嵌入向量驱动，存储在专门的 embeddings 表中，按 family 索引。

写入流程：新 memory / note 落盘后异步触发 embedding 生成，引用持久化到 frontmatter 的 `embedding_ref` 字段，避免重复计算。

读取流程：当用户启动新的代理会话或显式触发 briefing 时：

1. 取当前上下文（用户目标、最近几条消息）作为查询文本；
2. 计算查询向量，按 family 在 `internal/store/embeddings.go` 维护的索引中检索 top-k 相似条目；
3. 按 family 聚合、由简报生成器压缩后注入到会话前置位置。

v0.3.1 把简报输出收紧了—— clean truncation、subset header、丢弃 no-summary findings，避免噪声条目污染上下文；同时，自 v0.3.0 起，briefing 的 auto-inject 阈值、最大条数、字符上限等参数暴露在 Console 的 Settings 中，用户可以针对不同 family 调整。

```mermaid
flowchart LR
  A[新会话上下文] --> B[查询向量]
  B --> C{embeddings 检索}
  C --> D[top-k memories/notes]
  D --> E[family 聚合]
  E --> F[briefing 摘要]
  F --> G[注入系统消息]
```

资料来源：[internal/store/embeddings.go:1-140]()、[internal/briefing/briefing.go:1-120]()、[internal/store/memories.go:160-220]()

## 归属机制：每条知识都标注 harness 与 model

自 v0.3.7 起，归属（attribution）成为记忆、笔记、会话的横切维度，让多模型协作场景下的来源追溯成为可能。

写入侧：

- `internal/store/attribution.go` 负责在每次落库时记录产生该条目的 harness（如 `claude-code`、`codex`）与 model 标识，写入 frontmatter 与 store 元数据。
- Codex 路径通过 client-derived ambient identity（cc/codex）解析客户端身份；其 stop-hook 引入心跳 + rollout tail-harvest（v0.3.3），确保即便代理被强制终止，落库条目仍能正确归属。
- 通过 `seam mcp-proxy` 的 stdio↔HTTP 桥接（v0.3.3），stdio 客户端也能正确触发归属写入。

读取侧：Console 的 Library 视图在每张卡片上同时呈现 harness pill 与 model pill（v0.3.7），让用户在统一布局内横向对比不同模型产出的知识，从而判断"哪条记忆来自哪个模型"并按需隔离或合并。

```text
示例 frontmatter:
---
schema: memory
created_at: 2026-01-12T08:30:00Z
family: web-app
source_session_id: ses_3a1f
embedding_ref: emb_91c2
harness: codex
model: gpt-5
---
```

跨模型迁移策略：由于归属字段与具体模型解耦，切换 harness 时只需新增条目归属，原条目仍可继续检索与引用，不会丢失历史。

资料来源：[internal/store/attribution.go:1-100]()、[internal/store/sessions.go:40-140]()、[internal/console/library.go:60-160]()

## 与其他模块的关系

- **Hook 层**：会话结束 / stop 时由 hook 把片段写入 memory / note，是写入入口。
- **Console Library**：统一访问、筛选、按 family 与归属过滤的可视化层（v0.3.6 + v0.3.9）。
- **briefing 服务**：把检索结果压缩为简报，注入到新会话，与 `seamlessd` 协同托管。
- **更新与安装链路**：v0.3.5 起跨 OS 的 `seamlessd start|stop|restart|status` 确保上述存储与简报在升级后保持连续。

资料来源：[internal/console/library.go:1-60]()、[internal/briefing/briefing.go:1-60]()

---

<a id='page-3'></a>

## 任务协调、计划、试验与 Gardener 策展

### 相关页面

相关主题：[系统总览、架构与构建流程](#page-1), [记忆、笔记、检索与归属](#page-2), [Console、MCP、Hooks 与跨平台部署运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [internal/store/tasks.go](https://github.com/0spoon/seamless/blob/main/internal/store/tasks.go)
- [internal/store/tasks_claim.go](https://github.com/0spoon/seamless/blob/main/internal/store/tasks_claim.go)
- [internal/store/tasks_deps.go](https://github.com/0spoon/seamless/blob/main/internal/store/tasks_deps.go)
- [internal/store/tasks_plans.go](https://github.com/0spoon/seamless/blob/main/internal/store/tasks_plans.go)
- [internal/store/trials.go](https://github.com/0spoon/seamless/blob/main/internal/store/trials.go)
- [internal/store/projects.go](https://github.com/0spoon/seamless/blob/main/internal/store/projects.go)
- [internal/store/gardener.go](https://github.com/0spoon/seamless/blob/main/internal/store/gardener.go)
- [internal/store/console_labs.go](https://github.com/0spoon/seamless/blob/main/internal/store/console_labs.go)
</details>

# 任务协调、计划、试验与 Gardener 策展

## 概述与定位

Seamless 的"任务/计划/试验"子系统位于控制台（Console）的 **Library 库区**内，承担多模型协作会话中"待办—计划—实验"三件套的协调与策展职责。它与项目族（project families）绑定，并通过 **Gardener** 后台循环主动整理孤儿（orphans）、沉没（sunk）任务与无主的 Plan/Trial。

该子系统的核心数据载体由以下文件定义：

- `tasks.go`、`tasks_claim.go`、`tasks_deps.go`：任务的 CRUD、声明（claim）与依赖图；
- `tasks_plans.go`：从一组已声明任务聚合出 **Plan**（执行草案）；
- `trials.go`：试验记录（绑定会话、harness、模型归属），用于回溯与对比；
- `gardener.go`：周期性巡检与策展（curation）逻辑；
- `console_labs.go`：v0.3.9 新增的 Labs / Trials 库屏渲染层。

资料来源：[internal/store/tasks.go:1-40]() [internal/store/trials.go:1-30]()

## 任务模型与生命周期

### 字段与状态机

任务以纯存储结构暴露，核心字段包括 `id`、`title`、`status`、`assignee_model`、`project_id`、`deps []string`、`source_session` 等。`status` 取值覆盖 `open → claimed → running → done | failed | sunk` 六个终态/中间态。

```go
type Task struct {
    ID            string
    Title         string
    Status        string  // open | claimed | running | done | failed | sunk
    ProjectID     string
    AssigneeModel string
    Deps          []string
    SourceSession string
    CreatedAt     time.Time
    UpdatedAt     time.Time
}
```

资料来源：[internal/store/tasks.go:42-90]()

### 声明与依赖解析

- **声明**：`tasks_claim.go` 中的 `Claim(taskID, modelID)` 使用原子比较并设置状态为 `claimed`，要求当前状态必须是 `open`，且所有 `Deps` 指向的任务均已 `done`。
- **依赖图**：`tasks_deps.go` 提供 `DepsReady(taskID)` 与 `DetectCycles(projectID)`，后者在写入前对项目内的 DAG 做拓扑校验，避免死锁。

资料来源：[internal/store/tasks_claim.go:15-70]() [internal/store/tasks_deps.go:20-80]()

## 计划（Plans）与试验（Trials）

### Plan 的聚合

`tasks_plans.go` 把同一项目族下、状态为 `claimed | running | open` 的任务按拓扑序归并为一条 **Plan**，并附带预算（token 上限）与预计步数。Plan 既可由 Gardener 周期性生成，也可由用户在 Console 显式触发。

### Trial 的归属

`trials.go` 中定义的 Trial 是 **一次任务执行的快照**，它把 `session_id`、`harness`（例如 cc/codex）、`model`（产生方归属，由 v0.3.7 引入的 attribution 字段填充）三件信息绑定到任务结果上，使后续的对比、回放、引用都以 Trial 为单位进行。

资料来源：[internal/store/tasks_plans.go:30-110]() [internal/store/trials.go:40-95]()

## Gardener 策展循环

`gardener.go` 实现了一个**轻量后台策展器**，定时或在事件触发下做以下事：

1. 扫描所有项目的 open/claimed 任务，对长时间无心跳的 `running` 任务标记为 `sunk`；
2. 回收孤儿：把不属于任何活跃 project family 的任务归集到一个"墓碑"项目以供审计；
3. 将满足依赖条件的零散任务聚合成新的 Plan draft；
4. 对过期或无主的 Trial 进行压缩存档。

该循环的输出会被 `console_labs.go` 在 v0.3.9 的 **Labs / Trials** 库屏上呈现，包括"草稿计划"、"进行中试验"与"已归档试验"三类视图。

资料来源：[internal/store/gardener.go:1-140]() [internal/store/console_labs.go:25-90]()

## 数据流与库屏呈现

```mermaid
flowchart LR
    A[Session/Harness] -->|记录 trial| B(trials.go)
    C[用户/Agent] -->|声明 task| D(tasks_claim.go)
    D --> E[tasks.go 存储]
    E -->|周期巡检| F(gardener.go)
    F -->|聚合| G[tasks_plans.go]
    G -->|渲染| H(console_labs.go)
    B --> H
    E -->|依赖校验| I(tasks_deps.go)
```

库屏共享统一的"reader nav strip + library chrome"，确保 Labs / Trials 与已有的 Notes、Memories、Tasks、Plans 视觉一致。

资料来源：[internal/store/console_labs.go:1-50]()

## 关键设计取舍

- **去中心化声明**：任务通过 `Claim` 自助抢占，无需中央调度器，便于多 harness 并发；
- **Trial 作为引用单元**：把归属（harness + model）与结果解耦，方便后续做模型对比与回放；
- **Gardener 兜底**：避免任务表因长时间运行而膨胀，与项目族（`projects.go`）联动做归属判定。

资料来源：[internal/store/projects.go:60-120]() [internal/store/gardener.go:100-140]()

---

<a id='page-4'></a>

## Console、MCP、Hooks 与跨平台部署运维

### 相关页面

相关主题：[系统总览、架构与构建流程](#page-1), [记忆、笔记、检索与归属](#page-2), [任务协调、计划、试验与 Gardener 策展](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [internal/console/console.go](https://github.com/0spoon/seamless/blob/main/internal/console/console.go)
- [internal/console/library.go](https://github.com/0spoon/seamless/blob/main/internal/console/library.go)
- [internal/console/labs.go](https://github.com/0spoon/seamless/blob/main/internal/console/labs.go)
- [internal/console/trials.go](https://github.com/0spoon/seamless/blob/main/internal/console/trials.go)
- [internal/console/sse.go](https://github.com/0spoon/seamless/blob/main/internal/console/sse.go)
- [internal/console/families.go](https://github.com/0spoon/seamless/blob/main/internal/console/families.go)
- [internal/console/memories.go](https://github.com/0spoon/seamless/blob/main/internal/console/memories.go)
- [internal/codex/mcp.go](https://github.com/0spoon/seamless/blob/main/internal/codex/mcp.go)
- [internal/codex/skills.go](https://github.com/0spoon/seamless/blob/main/internal/codex/skills.go)
- [internal/codex/mcp_proxy.go](https://github.com/0spoon/seamless/blob/main/internal/codex/mcp_proxy.go)
- [internal/codex/stop_hook.go](https://github.com/0spoon/seamless/blob/main/internal/codex/stop_hook.go)
- [internal/hooks/hooks.go](https://github.com/0spoon/seamless/blob/main/internal/hooks/hooks.go)
- [cmd/seam/hook.go](https://github.com/0spoon/seamless/blob/main/cmd/seam/hook.go)
- [internal/service/service.go](https://github.com/0spoon/seamless/blob/main/internal/service/service.go)
- [internal/service/posix.go](https://github.com/0spoon/seamless/blob/main/internal/service/posix.go)
- [internal/service/windows.go](https://github.com/0spoon/seamless/blob/main/internal/service/windows.go)
- [internal/install/picker.go](https://github.com/0spoon/seamless/blob/main/internal/install/picker.go)
- [internal/update/update.go](https://github.com/0spoon/seamless/blob/main/internal/update/update.go)
- [cmd/seamlessd/main.go](https://github.com/0spoon/seamless/blob/main/cmd/seamlessd/main.go)
</details>

# Console、MCP、Hooks 与跨平台部署运维

本页面向读者介绍 Seamless 在 v0.3.x 周期内集中演进的四个面向用户的子系统：Web Console（资源库界面）、MCP 集成与 Skills、Hooks 生命周期、以及 `seamlessd` 守护进程与跨平台安装/升级流程。它们共同构成了"客户端 harness ⇄ 后台服务 ⇄ 运维工具链"的完整链路。

## 1. Console：统一的资源库 (Library) 布局

Console 是 Seamless 提供给本地用户的 Web 控制台，负责把原本分散的实体收纳到一致的"资源库 (Library)"骨架中，让浏览器侧拥有一致的导航、筛选与阅读体验。

- v0.3.6 将 Notes、Memories、Tasks 合并为统一布局，并在后续把 Plans 接入同一框架，从此资源库成为所有"可读对象"的统一入口。
  资料来源：[internal/console/console.go:40-180]()
  资料来源：[internal/console/library.go:1-90]()
- v0.3.9 新增 Labs 与 Trials 屏幕，并提供跨页通用的"读者导航条 (reader nav strip)"与共享 chrome，资源库体验完成收敛。
  资料来源：[internal/console/labs.go:1-60]()
  资料来源：[internal/console/trials.go:1-60]()
- v0.3.9 进一步在 Settings 中开放项目族 (project families) 的编辑入口，并把覆盖面纳入"reach card"指标，运维侧可直观看到家族影响范围。
  资料来源：[internal/console/families.go:20-140]()
- 控制台通过 SSE 通道向浏览器推送实时状态，因此前端无需轮询即可看到记忆/会话新增。
  资料来源：[internal/console/sse.go:30-150]()
- v0.3.7 引入"harness / model 归属 (attribution) 徽标"，展示每条记忆、笔记与会话由哪个 harness 与模型产出，便于追溯。
  资料来源：[internal/console/memories.go:60-180]()

## 2. MCP 接入与 Skills

Seamless 通过 MCP (Model Context Protocol) 与外部工具/数据源对接，并提供 native skills，使客户端在调用上下文时直接携带这些能力，无需依赖外部注册表。

- v0.3.7 在 Codex 端补齐 MCP 使用说明，并落地 native skills，让客户端可在不改动 harness 的情况下消费工具集。
  资料来源：[internal/codex/mcp.go:1-120]()
  资料来源：[internal/codex/skills.go:20-100]()
- v0.3.3 提供 `seam mcp-proxy` 子命令，作为 stdio↔HTTP 桥接器，让只支持 stdio 传输的 MCP 客户端也能访问 HTTP 端点，显著降低客户端侧的接入门槛。
  资料来源：[internal/codex/mcp_proxy.go:40-180]()
- 同一版本引入 client-derived ambient identity (cc/codex)，客户端不再要求显式声明身份，而是从运行时上下文（环境变量、cwd 等）自动推断归属。
  资料来源：[internal/codex/mcp.go:140-220]()

## 3. Hooks：Stop-hook 生命周期与 exec-form 配置

Hooks 是 Seamless 与外部 harness 的契约点，决定何时把"过程产物"沉淀为记忆/会话，也是 Stop-hook 在长任务中能可靠收尾的关键。

- v0.3.2 重写 hooks 的下发形式，统一为 exec-form 命令，并由 `seam hook --config` 暴露完整配置入口，避免客户端去解析复杂的声明式结构。
  资料来源：[internal/hooks/hooks.go:1-140]()
  资料来源：[cmd/seam/hook.go:30-160]()
- v0.3.3 在 Codex 路径上实现 Stop-hook 生命周期，包含：周期 heartbeat 与 rollout tail-harvest，确保长任务结束时仍能捕获尾部事件，不会因超时丢失最后一段上下文。
  资料来源：[internal/codex/stop_hook.go:50-200]()

下表总结了 Hooks 形态在 v0.3.x 中的演进：

| 维度 | v0.3.2 之前 | v0.3.3 起 |
|------|-------------|-----------|
| 下发形态 | 解释式 | exec-form 命令 |
| 配置入口 | 散落在文件 | `seam hook --config` |
| Codex 收尾 | 仅终止事件 | heartbeat + tail-harvest |
| 可观测性 | 较弱 | 周期心跳 + 尾部补采 |

## 4. 跨平台部署运维：seamlessd、安装与升级

守护进程 `seamlessd` 是后台常驻服务，负责承载 Console/MCP/Hooks 的所有状态。v0.3.x 在跨平台一致性方面做了大量收敛。

- v0.3.5 统一了 `seamlessd start|stop|restart|status` 跨 OS 语义，并在 `Makefile` 中提供等价 `make` 目标，开发与生产路径一致。
  资料来源：[internal/service/service.go:30-160]()
  资料来源：[internal/service/posix.go:1-120]()
- v0.3.2 落地 Windows 打包、安装与监管，通过 Windows SCM 直接驱动服务生命周期，与 POSIX 守护逻辑形成对称。
  资料来源：[internal/service/windows.go:1-140]()
- v0.3.4 引入交互式客户端选择器与非 Claude Code 环境的"graceful doctor"自检；v0.3.8 进一步要求用户显式确认客户端选择，去除静默回退到 Claude 的行为，避免误装。
  资料来源：[internal/install/picker.go:1-100]()
- v0.3.6 在 `seamlessd` 中加入 `update` 子命令与 `--check` 干跑模式，与 `make update` 行为一致，可在不实际替换二进制的前提下预演升级。
  资料来源：[internal/update/update.go:20-180]()
  资料来源：[cmd/seamlessd/main.go:40-200]()

整体拓扑可以概括为：CLI（`seam`、`seamlessd`）→ 后台服务（承载 Console/MCP/Hooks 状态）→ 浏览器端 Console 前端 + Codex/Claude 类客户端（经 MCP 与 Hooks 接入）。任何升级路径都推荐先经 `seamlessd update --check` 干跑，再由服务自身热加载，从而在 macOS、Linux 与 Windows 上保持一致的运维体验。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：0spoon/seamless

摘要：发现 22 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。

## 1. 能力坑 · 能力证据存在缺口

- 严重度：high
- 证据强度：source_linked
- 发现：Sandbox install result is missing.
- 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
- 证据：evidence.evidence_gaps | https://github.com/0spoon/seamless | Sandbox install result is missing.

## 2. 安装坑 · 可能需要本地编译工具链

- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装入口或说明出现本地编译相关关键词：make run
- 对用户的影响：Windows/macOS 用户可能卡在编译依赖上。
- 复现命令：`make run`
- 证据：identity.distribution | https://github.com/0spoon/seamless | make run

## 3. 安装坑 · 失败模式：installation: v0.3.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.3.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.3.1
- 证据：failure_mode_cluster:github_release | https://github.com/0spoon/seamless/releases/tag/v0.3.1 | v0.3.1

## 4. 安装坑 · 失败模式：installation: v0.3.2

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.3.2
- 对用户的影响：Upgrade or migration may change expected behavior: v0.3.2
- 证据：failure_mode_cluster:github_release | https://github.com/0spoon/seamless/releases/tag/v0.3.2 | v0.3.2

## 5. 安装坑 · 失败模式：installation: v0.3.3

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.3.3
- 对用户的影响：Upgrade or migration may change expected behavior: v0.3.3
- 证据：failure_mode_cluster:github_release | https://github.com/0spoon/seamless/releases/tag/v0.3.3 | v0.3.3

## 6. 安装坑 · 失败模式：installation: v0.3.4

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.3.4
- 对用户的影响：Upgrade or migration may change expected behavior: v0.3.4
- 证据：failure_mode_cluster:github_release | https://github.com/0spoon/seamless/releases/tag/v0.3.4 | v0.3.4

## 7. 安装坑 · 失败模式：installation: v0.3.5

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.3.5
- 对用户的影响：Upgrade or migration may change expected behavior: v0.3.5
- 证据：failure_mode_cluster:github_release | https://github.com/0spoon/seamless/releases/tag/v0.3.5 | v0.3.5

## 8. 安装坑 · 失败模式：installation: v0.3.7

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.3.7
- 对用户的影响：Upgrade or migration may change expected behavior: v0.3.7
- 证据：failure_mode_cluster:github_release | https://github.com/0spoon/seamless/releases/tag/v0.3.7 | v0.3.7

## 9. 安装坑 · 失败模式：installation: v0.3.8

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.3.8
- 对用户的影响：Upgrade or migration may change expected behavior: v0.3.8
- 证据：failure_mode_cluster:github_release | https://github.com/0spoon/seamless/releases/tag/v0.3.8 | v0.3.8

## 10. 安装坑 · 失败模式：installation: v0.3.9

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.3.9
- 对用户的影响：Upgrade or migration may change expected behavior: v0.3.9
- 证据：failure_mode_cluster:github_release | https://github.com/0spoon/seamless/releases/tag/v0.3.9 | v0.3.9

## 11. 安装坑 · 安装命令尚未沙箱验证

- 严重度：medium
- 证据强度：runtime_trace
- 发现：当前 install_status=documented，还只是文档/元数据线索。
- 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
- 复现命令：`make run`
- 证据：downstream_validation.install_status | https://github.com/0spoon/seamless | install_status=documented; command=make run

## 12. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/0spoon/seamless | host_targets=mcp_host, claude_code, claude, codex

## 13. 配置坑 · 失败模式：configuration: v0.3.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.3.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.3.0
- 证据：failure_mode_cluster:github_release | https://github.com/0spoon/seamless/releases/tag/v0.3.0 | v0.3.0

## 14. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/0spoon/seamless | README/documentation is current enough for a first validation pass.

## 15. 运行坑 · Quick Start 尚未实际跑通

- 严重度：medium
- 证据强度：source_linked
- 发现：quickstart_status=not_attempted。
- 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
- 证据：downstream_validation.quickstart_status | https://github.com/0spoon/seamless | quickstart_status=not_attempted; sandbox_quickstart_status=missing

## 16. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/0spoon/seamless | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/0spoon/seamless | no_demo; severity=medium

## 18. 安全/权限坑 · 存在安全注意事项

- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 证据：risks.safety_notes | https://github.com/0spoon/seamless | No sandbox install has been executed yet; downstream must verify before user use.

## 19. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/0spoon/seamless | no_demo; severity=medium

## 20. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/0spoon/seamless | issue_or_pr_quality=unknown

## 21. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/0spoon/seamless | release_recency=unknown

## 22. 维护坑 · 失败模式：maintenance: v0.3.6

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.3.6
- 对用户的影响：Upgrade or migration may change expected behavior: v0.3.6
- 证据：failure_mode_cluster:github_release | https://github.com/0spoon/seamless/releases/tag/v0.3.6 | v0.3.6

<!-- canonical_name: 0spoon/seamless; human_manual_source: deepwiki_human_wiki -->