跳至主要內容

AssetIWeave 对话记录：添加 App / 网页来源支持使用文档

util6大约 6 分钟

AssetIWeave 对话记录：添加 App / 网页来源支持使用文档

当前重构后的接入原则

新的对话记录接入方式以用户目录下的外置能力为边界：新增一个 App 或网页来源时，不应修改 AssetIWeave 应用源码，也不应把站点脚本放进仓库模板目录。

正确落点按来源类型拆分：

~/.assetiweave/conversation-adapters/<adapter-id>/  # 普通 App / Session adapter
~/.assetiweave/harvesters/<harvester-id>/            # 网页 harvester

AssetIWeave 只负责：

  • 安装或登记 adapter / harvester 目录。
  • 校验 conversation-adapter.json。
  • 按 manifest 中的相对命令执行用户目录里的 adapter 代码。
  • 把插件输出的标准化 Session / Web Record 写入数据库。
  • 在前端的 Session 浏览或网页记录浏览里显示结果。

关键概念

Adapter 插件

Adapter 插件负责把外部记录转换成 AssetIWeave 的标准对话格式。插件目录至少包含：

~/.assetiweave/conversation-adapters/my-app/
├── conversation-adapter.json
└── adapter.js

conversation-adapter.json 示例：

{
  "schema_version": 1,
  "id": "my-app",
  "name": "My App",
  "version": "0.1.0",
  "protocol_version": 1,
  "command": ["adapter.js"],
  "capabilities": ["probe", "read_session"],
  "input_kinds": ["directory"]
}

网页记录来源需要额外声明 web_records：

"capabilities": ["probe", "read_session", "web_records"]

注意：command 必须是插件目录内的相对路径，例如 adapter.js 或 scripts/adapter.js。不要写绝对路径。

Source 来源

Source 描述“去哪里读数据”。常见字段：

  • source_name：显示名称。
  • kind：来源类型，常用 directory，也可用 file、sqlite、live、custom。
  • location：传给插件的读取位置。
  • record_kind：session 或 web。

普通 App 对话进入 Session 浏览；网页 AI 对话进入网页记录浏览。

插件通信协议

执行器会把请求 JSON 写到插件标准输入。插件读取后，把 NDJSON 写到标准输出。

请求示例：

{
  "protocol_version": 1,
  "request_id": "sync-my-source",
  "method": "read_session",
  "source": {
    "location": "/path/to/export",
    "config": null
  },
  "params": {
    "session_id": null
  }
}

输出示例：

{"type":"item","item":{"kind":"session","session":{"external_id":"s1","title":"Example","project_path":null,"started_at":null,"updated_at":null,"source_locator":null,"source_fingerprint":"fingerprint","turns":[{"external_id":"t1","turn_index":0,"user_text":"问题","title":null,"started_at":null,"ended_at":null,"parts":[{"role":"assistant","kind":"text","text":"回答","language":null,"command":null,"cwd":null,"status":null,"exit_code":null,"metadata_json":null}]}]}}}
{"type":"complete","item":{"session_count":1,"turn_count":1}}

添加一个普通 App 来源

适用场景：某个本地 App、CLI 工具、数据库或导出目录已经有对话记录，你希望它出现在 Session 浏览里。

1. 创建插件目录

mkdir -p ~/.assetiweave/conversation-adapters/my-app

也可以用脚手架生成基础文件：

assetiweave-cli conversation adapter scaffold \
  --directory ~/.assetiweave/conversation-adapters/my-app \
  --id my-app \
  --name "My App"

2. 编写 adapter

实现 adapter.js 或其他可执行脚本。它需要读取 stdin 请求，从 source.location 读取原始数据，然后输出标准 NDJSON。

脚本要有可执行权限：

chmod +x ~/.assetiweave/conversation-adapters/my-app/adapter.js

3. 校验 manifest

assetiweave-cli conversation adapter validate \
  ~/.assetiweave/conversation-adapters/my-app/conversation-adapter.json

4. 试运行

assetiweave-cli conversation adapter try-run \
  ~/.assetiweave/conversation-adapters/my-app/conversation-adapter.json \
  --method read_session \
  --location ~/my-app-records \
  --yes

确认输出能解析出 Session 后，再添加来源。

5. 添加来源

assetiweave-cli conversation add \
  --plugin ~/.assetiweave/conversation-adapters/my-app \
  --source-id my-app-export \
  --source-name "My App Export" \
  --kind directory \
  --location ~/my-app-records \
  --record-kind session \
  --yes

conversation add 会登记插件和来源。默认会尝试同步；如果只是先登记，可加：

--no-sync

6. 同步并查看

assetiweave-cli conversation sync --adapter my-app

然后在前端进入 Session 浏览，按 App / Session / Question 查看。

添加一个网页 AI 来源

适用场景：支持 https://chatgpt.com/、Qwen、Gemini 或其他网页 AI 对话。

网页来源通常分两段：

  1. Harvester：读取浏览器登录态或网页 API，把网页对话抓取到本地标准文件。
  2. Adapter：把本地标准文件导入 AssetIWeave 的网页记录表。

推荐目录

~/.assetiweave/harvesters/chatgpt-web/
├── conversation-adapter.json
├── adapter.js
├── web-harvester.json
├── requests/
│   └── auth-probe.json
├── scripts/
│   └── harvest.js
└── output/
    └── normalized/
        └── sessions.json

1. 创建网页插件

如果是通用网页接口，可以先用 web 脚手架：

assetiweave-cli conversation web scaffold \
  --directory ~/.assetiweave/harvesters/site-web \
  --site site-web \
  --name "Site Web"

如果网页结构复杂，比如 ChatGPT 的 conversation mapping，需要单独实现 scripts/harvest.js 和 normalizer。

2. 获取或刷新登录态

以 ChatGPT 为例：

assetiweave-cli conversation web auth-detect \
  ~/.assetiweave/harvesters/chatgpt-web \
  --domain chatgpt.com \
  --credential cookie

校验登录态：

assetiweave-cli conversation web auth-check \
  ~/.assetiweave/harvesters/chatgpt-web

3. 抓取网页对话

如果插件使用自带采集脚本：

ASSETIWEAVE_HARVESTER_DIR=~/.assetiweave/harvesters/chatgpt-web \
  ~/.assetiweave/harvesters/chatgpt-web/scripts/harvest.js

采集完成后，应生成：

~/.assetiweave/harvesters/chatgpt-web/output/normalized/sessions.json

4. 添加网页记录来源

网页记录必须使用 --record-kind web：

assetiweave-cli conversation add \
  --plugin ~/.assetiweave/harvesters/chatgpt-web \
  --source-id chatgpt-web-export \
  --source-name "ChatGPT Web" \
  --kind directory \
  --location ~/.assetiweave/harvesters/chatgpt-web/output/normalized \
  --record-kind web \
  --yes

如果还没有生成 sessions.json，先加 --no-sync，等采集完成后再同步。

5. 同步网页记录

assetiweave-cli conversation sync --adapter chatgpt-web

查看网页记录：

assetiweave-cli conversation web-record list

前端进入“网页记录浏览”，即可看到按站点、网页会话、问题组织的内容。

用前端添加来源

前端入口适合已经准备好插件目录和数据目录后使用。

  1. 打开 Session 浏览或网页记录浏览。

  2. 点击“添加来源”。

  3. 普通 App 选择“插件目录”；网页记录选择“Harvester 文件夹”，例如：

    ~/.assetiweave/harvesters/chatgpt-web

  4. 填写来源名称。

  5. 选择来源类型，通常是“目录”。

  6. 选择来源位置：

    • 普通 App：原始导出目录或 adapter 约定的目录。
    • 网页记录：前端选择 harvester 根目录，后台登记来源时使用其中的 output/normalized。

  7. 提交后再执行同步。

网页记录来源要确保当前页面处于网页记录模式，或者 CLI 中明确传 --record-kind web。

如何判断该用 App 还是网页记录

用 Session 来源：

  • Codex、Claude Code、OpenCode 等本地工具记录。
  • 本地 App 导出的 JSON、SQLite、日志目录。
  • 内容是“工具会话”或“项目上下文”。

用网页记录来源：

  • ChatGPT、Qwen、Gemini 等网页对话。
  • 数据来自浏览器登录态或网页 API。
  • 想在独立的网页记录浏览里查看，不混入普通 Session 列表。

常见问题

前端没有显示新增条目

检查三点：

  1. 是否已经添加 source：

    assetiweave-cli conversation source list

  2. 是否已经同步：

    assetiweave-cli conversation sync --adapter <adapter-id>

  3. 网页来源是否用了 web_records capability 和 --record-kind web。

提示 command 必须是相对路径

conversation-adapter.json 中不要写：

"command": ["/Users/me/plugin/adapter.js"]

应该写：

"command": ["adapter.js"]

插件会从自己的目录执行。

提示插件已存在

目标目录已经存在：

~/.assetiweave/conversation-adapters/<plugin-id>

可以选择：

  • 换一个 --plugin-id。
  • 手动备份并删除旧目录。
  • 直接复用已有目录，不重复安装。

同步成功但导入为空

先用 try-run 看插件输出：

assetiweave-cli conversation adapter try-run \
  ~/.assetiweave/conversation-adapters/<plugin-id>/conversation-adapter.json \
  --method read_session \
  --location <source-location> \
  --yes

如果 try-run 没有输出 item 行，问题在插件解析或 location。

网页登录失效

重新执行：

assetiweave-cli conversation web auth-detect <plugin-dir> --domain <domain> --credential cookie
assetiweave-cli conversation web auth-check <plugin-dir>

然后重新采集和同步。

安全注意事项

  • 插件代码会被本机执行，先审查再 --yes。
  • 不要把浏览器 Cookie、access token、原始网页响应提交到代码仓库。
  • Session adapter 目录应放在 ~/.assetiweave/conversation-adapters。
  • 网页 harvester 目录应放在 ~/.assetiweave/harvesters。
  • manifest 的命令必须是插件目录内的相对路径。
  • 不要使用 symlink 或特殊文件包装插件脚本。

最小接入清单

普通 App：

准备插件目录 -> 写 conversation-adapter.json -> 写 adapter -> validate -> try-run -> conversation add --plugin -> conversation sync -> 前端查看

网页来源：

准备网页 harvester 目录 -> auth-detect/auth-check -> harvest 生成 sessions.json -> conversation add --plugin --record-kind web -> conversation sync -> 网页记录浏览查看
util6 knowledge hub
Copyright © 2026 util6