Paperclip 的反馈投票数据保存在哪里？如何用 CLI 查看和导出本地投票记录？
【免费下载链接】paperclipThe open-source app everyone uses to manage agents at work项目地址: https://gitcode.com/GitHub_Trending/papercl/paperclip
你在 Paperclip 里对 agent 的回复点了Helpful（赞）或Needs work（踩）之后，可能想知道：这些投票到底存在哪里，能不能在终端里快速看一份汇总，能不能把全部投票连同上下文快照打包导出来备份或交给分析流程。本文基于 docs/feedback-voting.md 和 doc/CLI.md，给出"数据存储位置 → CLI 查看 → CLI 导出"这条可核对的路径。前提是你有一个正在运行的本地 Paperclip 实例，以及可用的paperclipaiCLI（仓库内用pnpm paperclipai脚本，或已安装的npx paperclipai/paperclipai）。
投票数据保存在哪里
每次投票都会在本地 Paperclip 数据库中产生两条记录，全部随你的运行实例保存在本机，除非你显式选择分享，否则不会离开你的机器：
| 记录 | 内容 |
|---|---|
| Vote（投票） | 你的投票方向（up/down）、可选的原因文本、分享偏好、consent 版本、时间戳 |
| Trace bundle（跟踪包） | 完整上下文快照：被投票的评论/文档修订文本、issue 标题、agent 信息、你的投票与原因——足以孤立理解这条反馈 |
物理位置上，本地 Paperclip 数据位于选定的实例根目录下。PAPERCLIP_HOME（默认~/.paperclip）决定主目录，PAPERCLIP_INSTANCE_ID决定实例，内嵌 PostgreSQL 数据就在实例根目录的db/下（见 doc/CLI.md 的 Local Storage Defaults 一节）：
~/.paperclip/ # PAPERCLIP_HOME └── instances/ └── default/ # 实例根目录 ├── db/ # 内嵌 PostgreSQL 数据 └── ...投票本身没有独立的"投票表文件"可以直接 cat，而是通过 CLI 和 API 从数据库读取。每条投票还有一个导出状态，决定它是否会被上传：
| 状态 | 含义 |
|---|---|
local_only | 仅本地保存，未标记分享 |
pending | 已标记分享，等待立即上传尝试 |
sent | 已成功传输 |
failed | 传输失败（如后端不可达），后台 flush worker 后续重试 |
无论状态如何，本地数据库始终保留完整的投票与 trace 数据。标记为 "keep local" 的投票永远不会进入导出队列。
用 CLI 查看本地投票记录
快速报告
最直接的方式是终端报告命令：
# 仓库内（开发脚本形式） pnpm paperclipai feedback report # 已安装 CLI paperclipai feedback report报告是带颜色的汇总：票数统计、每条 trace 的详情（含原因）以及导出状态。如果没有任何投票，报告会显示No feedback traces found.。
常用变体：
# 指向另一个 server 或公司 npx paperclipai feedback report --api-base http://127.0.0.1:3000 --company-id <company-id> # 在报告中包含原始 payload 转储 pnpm paperclipai feedback report --payloads其中<company-id>替换为你公司的实际 ID。若不传--company-id，CLI 会依次使用PAPERCLIP_COMPANY_ID环境变量或 CLI context 默认值（可用npx paperclipai context set --api-base ... --company-id <id>配置，见 docs/cli/overview.md）。
通过 API 端点核对单条数据
CLI 报告之外，可以直接用 API 查看，便于脚本化核对。以下端点都需要 board-user 权限（本地开发环境自动满足）。注意 docs/feedback-voting.md 的示例使用127.0.0.1:3102端口，而文档其他位置给出的默认服务器端口是3100（见 docs/deploy/environment-variables.md），请替换为你实例实际的 api-base：
# 列出某个 issue 的全部投票 curl http://127.0.0.1:3102/api/issues/<issueId>/feedback-votes # 列出某个 issue 的 trace bundles（含完整 payload） curl 'http://127.0.0.1:3102/api/issues/<issueId>/feedback-traces?includePayload=true' # 列出全公司的 trace curl 'http://127.0.0.1:3102/api/companies/<companyId>/feedback-traces?includePayload=true' # 获取单条 trace 记录 curl http://127.0.0.1:3102/api/feedback-traces/<traceId> # 获取一条 trace 的完整导出 bundle curl http://127.0.0.1:3102/api/feedback-traces/<traceId>/bundletrace 端点支持的查询参数：
| 参数 | 取值 | 说明 |
|---|---|---|
vote | up、down | 按投票方向过滤 |
status | local_only、pending、sent、failed | 按导出状态过滤 |
targetType | issue_comment、issue_document_revision | 按被投票对象类型过滤 |
sharedOnly | true | 只看用户选择分享的投票 |
includePayload | true | 包含完整上下文快照 |
from/to | ISO 日期 | 日期范围过滤 |
另外，doc/CLI.md 列出了按 ID 直接取单条记录的形式，适合自动化导出流程：
npx paperclipai feedback trace <trace-id> npx paperclipai feedback bundle <trace-id>按 issue 查看投票也有专门命令：
npx paperclipai issue feedback:votes <issue-id>用 CLI 导出本地投票记录
导出到文件 + zip
pnpm paperclipai feedback export默认导出为全量，会创建一个带时间戳的目录和一个同名 zip。文档给出的目录结构示例如下（目录名为文档示例，实际按运行时间生成）：
feedback-export-20260331T120000Z/ index.json # 清单，含汇总统计 votes/ PAP-123-a1b2c3d4.json # 投票元数据（每条投票一个文件） traces/ PAP-123-e5f6g7h8.json # Paperclip feedback envelope（每条 trace 一个文件） full-traces/ PAP-123-e5f6g7h8/ bundle.json # 该 trace 的完整导出清单 ...raw adapter files # 可用时的 codex / claude / opencode 会话原始文件 feedback-export-20260331T120000Z.ziptraces/保留 Paperclip envelope，full-traces/包含更丰富的逐条 bundle 以及可恢复的 adapter 原生文件。指定自定义服务器与输出目录：
npx paperclipai feedback export --api-base http://127.0.0.1:3000 --company-id <company-id> --out ./my-export两个执行层面的注意点：
- 输出目录必须不存在或为空，已存在非空目录会直接报错，不会覆盖旧导出；
- 导出只读取本地数据库并写入
--out指定位置，不修改数据库本身。
验证导出结果
导出完成后，命令会打印一段Paperclip Feedback Export摘要，列出公司 ID、输出目录、zip 路径，以及 thumbs up / thumbs down / with reason / unique issues 计数和文件数量。进一步的核对方式：
- 打开导出目录中的
index.json，它是清单文件，包含exportedAt、serverUrl、companyId、汇总统计以及files下 votes/traces/fullTraces/zip 的完整文件列表； - 打开
traces/中任意文件查看上下文快照。文档示例（值为示例，不是固定预期）：
{ "id": "trace-uuid", "vote": "down", "issueIdentifier": "PAP-123", "issueTitle": "Fix login timeout", "targetType": "issue_comment", "targetSummary": { "label": "Comment", "excerpt": "The first 80 chars of the comment that was voted on..." }, "payloadSnapshot": { "vote": { "value": "down", "reason": "Did not address the root cause" }, "target": { "body": "Full text of the agent comment..." }, "issue": { "identifier": "PAP-123", "title": "Fix login timeout" } } }- 打开
full-traces/<issue>-<trace>/bundle.json，可以看到扩展的导出元数据（capture notes、adapter 类型、完整性元数据、写入的原始文件清单）。bundle.json.files[]中每个条目把捕获的文件内容放在contents字段里，而不是只有路径；文本产物以 UTF-8 存储，二进制产物用 base64 加encoding标记。内置本地 adapter 会直接导出原生会话文件，例如codex_local的adapter/codex/session.jsonl、claude_local的adapter/claude/session.jsonl（含 sidecar 与debug.txt，若存在）、opencode_local的adapter/opencode/session.json等。
限制与边界
- 分享偏好按公司保存，首次投票时由 consent 对话框选择 "Keep local" 或 "Share this vote"，之后可随时在反馈设置中更改；
- 标记分享的 trace 会尝试立即上传到 Telemetry Backend（未配置后端 URL 时回退到
https://telemetry.paperclip.ing），失败会进入failed状态等待重试。上传的是投票时刻的快照：如果底层 adapter 会话文件之后继续增长，本地重新生成的 bundle 可能比已上传快照更大； - 已分享对象在远端对象存储中的 key 为确定性模式
feedback-traces/<companyId>/YYYY/MM/DD/<exportId-or-traceId>.json，便于核对上传结果； - 端口提示再次说明：本文 curl 示例沿用了 docs/feedback-voting.md 原文的
3102，若你的实例按默认端口运行，请把 host:port 替换为实际 api-base。
完成一次feedback report确认计数与状态、再跑一次feedback export核对index.json与实际文件，就是这条数据从产生、查看到导出的完整闭环验证。
【免费下载链接】paperclipThe open-source app everyone uses to manage agents at work项目地址: https://gitcode.com/GitHub_Trending/papercl/paperclip
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
