AI 技能AI 写作人工智能深度研究AI 应用【免费下载链接】PaperSpinePaperSpine5 — local-first, evidence-bound paper research, writing, figures, review and delivery. Download: https://wubing2023.github.io/PaperSpine/v5/项目地址https://gitcode.com/gh_mirrors/pa/PaperSpine点击查看免费下载导读PaperSpine5 是一套 local-first、证据绑定的论文研究/写作/图表/评审/交付工作流而execution-efficiency.md仓库原文定义的是贯穿整套流程的执行效率契约在绝不跳过用户要求的科学工作的前提下复用已经验证的有效成果、停止无产出的重试。本文基于该文档并深入execution_receipt.py、usage_ledger.py、visual_readiness_check.py及其测试用例完整讲解单次读取指令集One-Read Instruction Set、基于 SHA-256 哈希绑定的执行凭证Execution Receipt、渲染器预检、有界失败恢复Bounded Failure Recovery与增量工作/最终全量检查并给出可直接落地的命令与配置细节。读完本文你将能在 PaperSpine 工作流中正确区分可复用的计算身份与科学就绪性避免把缓存命中误当作质量通过。一、核心原则复用有效工作但绝不跳过要求的科学本文档的出发点是一条看似矛盾、实则统一的纪律复用Reuse与不跳过No Skip同时成立。复用边界已经验证的、输入输出快照未变的成果可以原样复用工具输出摘要永远不能替代底层哈希绑定的源材料。不跳过边界阶段标签stage label不能代替原版科学方法凭证复用只证明计算身份不推断scientific_content_ready、visual_ready、引用正确性、作者批准、投稿就绪或授权。在 PaperSpine 的当前公开主机工作流中本方法只服务于当前范围交付current-scope delivery不引入新的状态门禁status gates。它是一份执行纪律而不是新的审批关卡。这与 SKILL.md 中的质量规则一脉相承Tool success, hashes and task status do not establish scientific, editorial, visual or submission readiness; assess the actual paper.工具成功、哈希与任务状态不构成科学、编辑、视觉或投稿就绪必须评估真实论文本身。二、One-Read 指令集单次读取、按需恢复1. 按需读取的文档集合针对当前公开主机工作流首次执行时只需读取SKILL.mddist/claude/skills/paper-spine/SKILL.md本文档本身product-v1-workflow.mddist/claude/skills/paper-spine/references/product-v1-workflow.md科学方法的选路通过current-method-routing.mddist/claude/skills/paper-spine/references/current-method-routing.md进行。文档特别强调旧的resume.md与product-runner-host-route.md管理命令仅适用于显式选择的遗留 Runner普通论文工作不应进入该旧路径。从源码结构可以推断product-v1-workflow.md是当前公开任务/工件/评审的权威入口而resume.mddist/claude/skills/paper-spine/references/resume.md中保留了遗留扁平输出恢复循环与ProductRunner 恢复循环两套旧机制仅用于旧任务恢复。2. 阅读实际工作所需的方法含依赖读取实际工作适用的方法包括其点名的依赖文件。一个阶段标签如draft、review不能替代原版科学方法的完整约束。current-method-routing.md同样指出method_guidance只是任务快照的建议性字段不记录主机已经读过它们也不证明论文已通过其检查。3. 紧凑续接笔记compact continuation note每到一个真实阶段边界、中断点或完成点保留一份紧凑续接笔记包含相同的 profile/task实际任务版本task version最后消费的事件序号event sequence相关源/输出路径待决决策与下一步动作。product-v1-workflow.md对此给出了精确的 API 语义paperspine_list_task_events支持after_sequence游标省略时默认从 0 返回全部历史任务版本与事件序号是两个不同的游标不能互相推断。Runner token/修订号与 gate 凭证只属于显式遗留工作流普通主机工作不产生这些对象。4. 复用未变输出拒绝重放历史不要每次迭代都重放完整任务历史或重载所有源材料只恢复下一步动作真正缺失的上下文。对于重要结论性笔记必须回到原始段落核对不能仅凭笔记记忆断言事实。5. 大证据按范围读取并保存坐标大篇幅证据按 page/section/line 范围读取并保存源坐标。工具输出摘要永远不能替代底层哈希绑定的源材料。这一点在current-method-routing.md的方法读取接口中有落地实现host methods --local --resource path --format text --start-line 1 --max-lines 100返回的文本帧包含源 SHA-256、范围、END 标记必须收到完整帧才算该页已接收缺少 END 意味着需要缩小--max-chars重试。跨页续读时用--start-line next --expect-sha256 same-source-hash保证同一源版本源变更会被报告而不是拼接不同版本。6. 全文件读取前的检查点记账在整文件读取前先把其路径、字节大小、SHA-256 与计划行范围记入紧凑检查点。绝不在工具输出预算可能超限时批量发起多个整文件读取若输出被截断只请求未读的行范围绝不从第 1 行重启。这一条与current-method-routing.md中文本帧默认 8000 字符按需降低--max-chars以适配宿主输出限额的约束相互印证。7. 区分工件复用与方法回忆工件artifact复用与方法回忆是两回事上下文丢失后即使文件未变也要重新打开下一步所需的原始段落。如果范围无法可靠定位就读完整方法。过去的已读标记不是知识必要的恢复不算repeated_read_miss不需要产生遥测凭证。8. 凭证失效条件出现以下任一情况相关检查点字段失效只需重载变更的权威及其下游 playbook而不是全量重读新任务版本或显式遗留 Runner 修订号材料快照变化手稿哈希变化目标target变化用户授权变化。product-v1-workflow.md给出配套纪律Task versions and event sequence numbers are different cursors: do not infer one from the other等待类操作应把最后观察到的 task version 传给实际 wait 工具超时不等于用户输入不得反复扫描转录。三、Expensive Operation Receipt昂贵操作凭证当精确缓存确实有用时仓库提供了可选的辅助工具execution_receipt.pysrc/scripts/execution_receipt.py来检查任务本地的凭证。普通论文工作不强制要求创建凭证——它只是昂贵的、确定性的操作PDF 渲染、DOCX 渲染、格式转换、引用审计快照等的优化手段。1. 检查命令与退出码python scripts/execution_receipt.py check \ --receipt paper_rewriting_output/execution_receipts/pdf-render.json \ --operation pdf-render --tool pdftoppmexact-version-or-path \ --input paper_rewriting_output/final_paper/paper.pdf \ --output paper_rewriting_output/visual_audit/pages退出码与语义与源码REUSABLE 0、MISS 3、ERROR 2一一对应退出码状态含义与动作0REUSABLE操作名、工具身份、完整输入快照、完整输出快照全部匹配 → 直接复用输出3MISS至少一项不匹配 → 运行一次操作、验证结果然后用相同参数执行record代替check记录新凭证2ERROR凭证损坏或输入缺失 → 修复畸形的/缺失的凭证输入不得称其为缓存命中从源码main()可以看出check分支对record是天然互斥的——record直接构建并原子写入凭证并返回REUSABLE(0)check则调用verify_receipt比较当前快照与凭证快照返回 0 或 3。--json标志可以输出结构化结果含findings与error字段便于程序化处理。2. 凭证的存储与覆盖范围凭证存放在paper_rewriting_output/execution_receipts/下位于被哈希的输出目录之外避免凭证自身污染输出快照。PDF 渲染、DOCX 渲染、格式转换、引用审计快照等昂贵确定性操作各自使用独立凭证。--tool必须包含每个可能改变结果的输入以及确切的可执行文件/版本/配置身份——这正是文档示例写pdftoppmexact-version-or-path的原因。3. 源码级实现细节build_receipt()生成的凭证字段CONTRACT paperspine.execution-receiptSCHEMA_VERSION 1.0{ contract: paperspine.execution-receipt, schema_version: 1.0, operation: pdf-render, tool_identity: pdftoppm..., created_at: UTC ISO 8601 时间戳, inputs: [ { path: ..., kind: file, size_bytes: 123, sha256: ... } ], outputs: [ ... ], scientific_readiness_inferred: false, visual_readiness_inferred: false }值得注意的实现事实哈希绑定snapshot_path()对文件计算 SHA-256 与字节数对目录则递归枚举成员按相对路径排序后对成员清单的规范 JSONsort_keysTrue、紧凑分隔符计算目录级 SHA-256并记录file_count。符号链接拒绝snapshot_path()显式拒绝符号链接links are not valid receipt inputs or outputs防止路径别名绕过哈希比较。去重校验snapshot_many()拒绝重复路径大小写折叠后去重避免同一路径既当输入又当输出造成的假命中。原子写入atomic_write_json()使用临时文件 os.replace()保证凭证写入过程崩溃也不会留下半截 JSON。逐项比较verify_receipt()依次核对 contract/schema version、operation、tool_identity、当前输入快照、当前输出快照并返回人类可读的findings如input snapshot differs。确定性操作专属凭证的适用对象是确定性的昂贵操作且从结构上写死scientific_readiness_inferred: false与visual_readiness_inferred: false从代码层面杜绝计算命中即质量通过的误用。4. 凭证的边界字节身份 ≠ 检查与质量文档明确列出凭证复用不能推断的结论scientific_content_ready、visual_ready、引用正确性、作者批准、投稿就绪、授权。人类或多模态检查只能对实际被检查的同一对象且依赖未受影响的情况复用。visual_readiness_check.py --preparesrc/scripts/visual_readiness_check.py是这一边界在视觉检查侧的落地--prepare渲染最终 PDF/图表并生成待审计清单visual_audit_manifest.json检查项初始为pending。_existing_prepare_is_reusable()只在完整准备的视觉快照精确一致时返回可复用——包括绑定 PDF/TeX 的哈希、每个 figure 资产的asset_sha256、渲染页的render_sha256、背景探测结果与设计豁免的当前性。任何绑定的 PDF、TeX、figure_requests.json、图表资产、渲染或 DPI 变化都会使清单重建为pendingreview.status重置为pending。测试 tests/test_readiness_gates.py 中的test_visual_prepare_reuses_exact_render_snapshot_without_erasing_review验证了快照完全一致时渲染器assert_not_called()不重复渲染且清单字节保持不变test_visual_prepare_invalidates_when_bound_pdf_changes验证了 PDF 变化后渲染器被调用一次、review.status变为pending。这正是凭证识别字节、而非检查或质量的测试级证据。四、Renderer Preflight渲染器预检每个环境只做一次渲染器可用性探测并把选定的可执行文件/版本记入凭证不要反复调用缺失的后端。PDF 页面渲染一次性预检pdftoppm与pdfinfo。从visual_readiness_check.py的实现看渲染器通过shutil.which(pdftoppm)探测缺失时返回pdftoppm not found页面盒探测通过pdfinfo -box执行缺失时记录pdfinfo not found。DOCX 表面渲染预检后从可用的、策略兼容的渲染器中选择一个。Windows 上可用时优先 Word 自动化LibreOffice仅在其可执行文件真实存在时使用——这排除了假设存在式的后端调用。渲染器失败不授权修改稿件内容必须保留源文件记录精确命令、退出状态与首个可操作的错误。五、Bounded Failure Recovery有界失败恢复对一条命令 一个未变化的输入快照恢复流程被严格限制为运行一次Run once。分类失败输入input、依赖dependency、环境environment、瞬时提供方transient provider、权限permission、契约contract或科学阻断scientific blocker。做一次具体的纠正性修改然后重试一次。绝不执行第三次实质上相同的尝试。改为报告阻断原因、精确证据、责任归属owner与恢复动作。补充纪律输入变化或依赖恢复可以构成重试理由但仅仅一个新哈希、新文件名或新任务版本不能重置一个未改变的缺陷。两次针对性修复后同一问题仍无改进改变方案/方法layout/method而不是继续微调坐标。保留一个可用版本、停止可选的打磨不要把错误的数字、不可读的标签或误导性的关系当作已修复呈现。任务零事件时的处理精确检查该任务一次 → 一次有界等待 → 一次最终状态读取不得在未变化的任务/线程状态上空转。干净替换任务clean replacement task仅在用户明确要求干净模拟/运行时才允许必须使用新的输出根目录且不得从失败任务导入答案或完成工件。这与SKILL.md的权威边界一致Never create a second task because a launcher, profile or transport failed.在遥测侧usage_ledger.pysrc/scripts/usage_ledger.py把重试次数可审计落为字段约束事件中的failure_category一旦出现就必须非空retry是必填字段。而 usage-telemetry.md 直接引用本方法the same command on the same input snapshot must not exceed one initial attempt plus one corrected retry同一命令在同一输入快照上不得超过一次初始尝试加一次纠正后的重试。六、Incremental Work, One Final Full Pass增量工作 一次最终全量检查逐段检查受影响的文件及其下游用途check affected files and their downstream use。在请求完整论文交付之前检查整篇论文的一致性与实际请求的格式。修复责任源owning source并复查受影响的输出一次聚焦评审或小修不需要重跑每一个历史审计命令也不需要强制额外的全量扫描。增量推进与交付前最终全量检查是互补关系日常以最小影响面工作交付前以全量一致性收口。这与SKILL.md的完成契约一致——actual renders inspected, not merely hashed or built实际渲染必须被检查而不仅仅是被哈希或构建。七、Usage Ledger执行的可观测性记录当宿主暴露以下观测数据时追加到paper_rewriting_output/usage_ledger.jsonlJSONL每模型调用或代理阶段一行实测的 tokens输入/缓存输入/推理/输出经过时间elapsed_ms重试次数retry复用或未命中状态execution_reusehit/miss/not_applicable凭证路径execution_receipt输入哈希input_hashes输出工件output_artifacts。源码usage_ledger.py的字段契约提供了更强的校验细节必填字段timestamp、stage、role、model、reasoning_effort、usage_source、gate_result、retryusage_source只允许api/host/telemetry_unavailableexecution_reuse只允许hit/miss/not_applicable且hit/miss必须同时提供execution_receipttoken 字段必须是非负整数实测值elapsed_ms同理usage_source: telemetry_unavailable时必须附带telemetry_note且不得伪造 token 计数。测试 tests/test_readiness_gates.py 的test_usage_ledger_validates_execution_reuse_receipts直接验证了这条规则带execution_reuse: hit与execution_receipt的事件通过删除execution_receipt后校验失败并产生requires execution_receipt结论。test_usage_ledger_accepts_explicit_unavailable_telemetry则验证了诚实降级路径宿主未返回用量时记录telemetry_unavailable事件整个 ledger 判定为UNAVAILABLE但通过诚实性检查。聚合与校验命令来自 usage-telemetry.mdpython scripts/usage_ledger.py paper_rewriting_output --markdown --write--write会生成按阶段汇总的token_budget_by_stage.md。最后一条铁律永远不要从文件大小估算计费 tokensNever estimate billed tokens from file size。八、整体工作流中的定位将上述机制串回 PaperSpine 的完整流程启动前更新预检paperspine_update.py --preflight --yes后按 One-Read 集合最小化读取通过current-method-routing.md定位真实方法日常增量工作严格复用未变输出检查受影响文件的下游对昂贵确定性操作渲染/转换/审计快照用execution_receipt.py check/record做哈希绑定复用凭证放execution_receipts/目录渲染前一次性预检pdftoppm/pdfinfo与 DOCX 渲染器失败按一次运行 → 分类 → 一次纠正重试 → 报告阻断的有界恢复执行交付前做一次最终全量一致性检查并把实测 tokens、经过时间、重试、复用状态与凭证路径记入usage_ledger.jsonl由usage_ledger.py校验聚合。这套方法不新增审批门禁而是把复用与不跳过两条纪律编码为命令、退出码与字段校验——这正是它区别于一般效率建议的工程价值所在。延伸阅读仓库内主编排文档SKILL.md公开主机工作流与任务文件product-v1-workflow.md方法选路与分页读取current-method-routing.md恢复/续接纪律resume.md凭证实现src/scripts/execution_receipt.py用量遥测校验src/scripts/usage_ledger.py、usage-telemetry.md视觉清单准备与复用src/scripts/visual_readiness_check.py测试证据tests/test_readiness_gates.py赞分享AI 技能AI 写作人工智能深度研究AI 应用【免费下载链接】PaperSpinePaperSpine5 — local-first, evidence-bound paper research, writing, figures, review and delivery. Download: https://wubing2023.github.io/PaperSpine/v5/项目地址https://gitcode.com/gh_mirrors/pa/PaperSpine点击查看免费下载相关推荐在 jevgrep 中实践有界工作与持续恢复audit-performance 技能的性能审计方法论在 jevgrep 中实践有界工作与持续恢复audit performance 技能的性能审计方法论 导读 audit performance 是 jevgr开发工具AI 应用代码智能体AI 技能/插件3步上手WezTermRust重写的GPU加速终端3步上手WezTermRust重写的GPU加速终端 当你在终端里同时挂着5个服务、日志刷得眼睛发花、还想切个窗口看张截图而旧终端已经开始掉帧、风扇狂转——那桌面应用开发工具跨平台Argo Workflows 工作规避Work Avoidance实战指南用 Marker 文件避免重复执行昂贵任务Argo Workflows 工作规避Work Avoidance实战指南用 Marker 文件避免重复执行昂贵任务 适用版本v2.9 及以后 导读 云原生容器编排工作流自动化任务调度后端上一篇终极GitHub中文插件指南5分钟快速安装告别英文困扰下一篇Windows右键菜单终极清理指南ContextMenuManager让你的桌面操作效率提升300%创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考