AGENTS.md git:20261027.acce28eA

Immutable. This exact content never changes and is served at /api/v1/blob/59532853849d2e57.

# 视频报告智能体——公开核心库

本仓库是公开的核心软件包，负责语音识别（ASR）、转写、Pi、共享生成技能（Skill）、渲染器和命令行工具。
托管服务的账户、额度、网站路由、管理后台和部署属于私有服务库。不得将私有源码复制到本仓库，也不得合并私有仓库的 Git 历史。

保持串行的 Python → Pi RPC → 生成技能主链，智能体循环由 Pi 负责。用户已授权主 Agent 按需通过图示工具启动至多一个独立 Pi 绘图会话，再由程序嵌入报告；该会话只接收局部材料，不增加规划、评判或其他编排角色。每次生成只向本次运行的工作目录写入内容。采用满足需求的最小改动，不增加未经需求支持的编排机制，不进行无关重构。

使用仓库内的 `.venv` 和 uv，运行相关测试。不得以固定测试样例的检查结果证明真实模型的生成质量。未经用户授权不得提交或推送。

维护文档和示例放在 `docs/`，本地实现笔记放在已忽略的 `.local/docs/`。

评测工具和经批准公开的冒烟测试、基准测试归核心库维护。真实来源的原始输入和实验结果放在核心库已忽略的 `.local/evals/`，不放在服务库。维护文档保存在所属仓库中，不纳入部署。

## 轻量评审

- 普通功能开发、接口或数据读写变更、缺陷修复完成实现和必要验证后，交付前由主智能体自动启动一个干净上下文的子智能体评审一次，无需另行确认。子智能体不继承实现对话；提供原始需求、验收要求、项目规则、变更基线和实际差异。评审者只读检查，不修改代码、不再委派评审；此流程仅用于开发阶段。
- 小的纯文案、说明文字或样式调整，确认不涉及行为变化时跳过独立评审，保留相应的内容或视觉验收。
- 权限、额度或支付、数据删除或迁移、并发、自动对外操作、关键部署配置属于高风险改动，即使改动很小也要评审；重点检查相关的权限边界、重复请求、数据一致性和失败处理，并做与风险相称的验证。
- 以一个完整改动为单位，可包含多个提交，不要求每个中间提交单独评审。只审本次差异及其影响范围，按需追踪相关调用链和测试；包含本次未提交改动，不混入已有无关修改，不扩大为全仓审计。
- 重点找实际缺陷、需求遗漏、旧功能回归和不必要的复杂化，并检查测试是否验证了预期行为。发现需给出代码位置、触发条件、实际后果和依据，区分确定问题与待验证疑点；不把开发者总结当作正确性证据，不为凑问题提出无关重构或个人风格建议。
- 主智能体核实发现后修复真实问题，运行必要检查；修复后只复查受影响部分，除非新证据表明影响更广。问题解决且相关验证通过即结束，不反复开启多轮全量评审。交付时简述评审结论或跳过原因，以及必要的未验证事项。

## 生成与验证

- 保持 Pi 的完成语义：仅收到 `agent_end` 不代表完成；消费端必须等待 `agent_settled`，并检查最终助手消息的 `stopReason == "stop"`。
- 流水线阶段事件保存在 `run.trace.jsonl`，智能体执行细节保存在 `pi.events.jsonl`。只扩展相关层，不借机统一日志或引入追踪框架。
- 对比报告质量时，除待测变量外，保持转写内容和生成设置不变。原文含义的保真度，包括数字、条件、归属和因果关系，应与 HTML 有效性、视觉布局分别评估；来源标识有效不代表内容忠实于原文。
- 修改报告模板或布局时，在可行的情况下，用具有代表性的渲染样例检查受影响的视口。若只做了静态检查或测试，需明确说明，并说明改动影响未来生成还是已有报告。不得默认重新生成历史报告。

## 报告设计迭代

- 重新设计局部组件前，先阅读所选模式的当前模板和 `docs/report-design-preferences.md`。使用有代表性的现有组件，在该模板内制作原型；除非用户要求重新设计页面，否则保留纸张、画布、字体排版和周围的视觉风格。
- 用户评审备选方案并明确选定其中一个时，例如选择“D”，视为授权将该方案应用到对应的生成技能或模板，并记录偏好。不要只切换预览、再次索要确认，或等待用户说出“采用”。如果用户明确只要求预览或保留样例，则遵守该范围。仅在所选方案或目标模式确实不明确时询问。
- 方案采用后，应用于所选模式的后续生成。提交、推送、部署和历史报告重新生成仍需分别获得用户授权。

## 报告生成技能维护

- 修改报告生成技能时，一并检查入口、所选模式和受影响的参考文件。共用规则放在入口，模式差异放在模式文件，参考文件只保留独立的编辑指导，并保持按需逐层加载。
- 新增规则前，检查现有规则或模板是否已经覆盖。优先合并或替换原文，在同一次改动中移除已被替代或重复的规则。新行为可以带来必要的内容增长，但不得将针对单份报告的临时处理默认为通用限制。
- 说明新增、合并或删除的内容，以及修改前后的 Markdown 总字符数。保留事实边界、模式约定和已采用的设计选择；行为变化时，使用现有评测工具，对比有代表性的固定输入报告，进行与改动相称的验证。
- 每周评审提出具体的删除或替换建议，并说明理由。不自动重写技能，不运行付费生成，也不采用待审核的设计建议；可执行的建议须由用户选择。评审记录放在 `.local/evals/`。

## 文档维护

本项目通过以下文档保存现状、后续方向和重要决策。执行项目任务或形成值得保留的项目讨论结论时，按实际影响维护相关内容，无需重新调用文档维护技能。

### 文档职责

- `docs/PROJECT.md`：项目解决的问题、目标与范围、当前能力、重要限制和文档入口。
- `docs/ARCHITECTURE.md`：当前系统结构、模块职责、关键流程、数据关系及重要接口。
- `docs/PLAN.md`：讨论过的候选方向、已确认的下一步和实际阻塞。
- `docs/DECISIONS.md`：影响后续开发的重要选择、决定性原因、约束、代价及替代关系。

项目概况和架构文档描述当前状态；已确认但尚未实现的设计标注待实现。具体配置与流程在架构或对应专题文档中完整维护，其他文档只保留必要摘要与链接。决策记录保存选择理由，项目计划保存未来事项，不重复抄写整套方案。

已有源码课程、面试材料或历史记录可以保留原用途；承担当前说明职责的部分应与现状一致，不能靠一条“以源码为准”保留错误。跨仓文档各自维护职责与接口，公共能力在所属仓库完整说明，产品集成在负责整体产品的仓库说明并引用，不向公开仓库复制私有内容。

### 开发前

较大功能、架构调整或跨模块修改前，阅读相关文档并结合代码理解实现；小范围修改按需查看。发现不一致时，区分文档过时、实现缺陷和方案变化，依据当前已确认方案处理；无法判断的重要约定保留并提出问题，不阻塞其他可继续工作。

### 文档更新

目标、能力、架构、数据、接口、重要依赖或策略发生变化，以及讨论形成有保留价值的方向时，更新对应文档。普通修复、样式或参数调整未使文档失真时，无需更新。

优先修改原说明，合并重复内容、删除失效说明；按变化检查关联的摘要、图表、示例和问答，不只在末尾追加日期补丁，也不扩大为全仓文档审计。README、部署和专题文档在原处维护，核心文档按需引用。

保持事实与状态准确，区分已实现、已验证和已部署。本轮未检查某项能力，不等于项目尚未实现或未投入使用，不自动产生待办。用户明确提供的使用情况应纳入相应说明；推断仍标明为推断。日期、提交基线和“不确定”说明仅在与具体内容有关时保留，不让某次调查范围长期代表整篇现状。

影响本次判断的价格、额度、地区可用性等外部信息，更新时核实官方来源并注明必要的适用条件；无需为无关的日常改动重查所有外部资料。

### 项目计划的维护

保存用户提出、讨论形成或用户要求保留的有价值方向。用简短文字说明想解决什么问题及关键背景，并区分候选、已确认、进行中或阻塞；仅在有依据时写优先级、时间和下一步。需要用户选择的关键问题放在相应事项下，不自行批准候选，也不为每个想法强制补齐实施方案。

相关讨论或任务使方向、状态或阻塞变化时，更新原事项。从项目计划中移除已完成且没有后续工作的事项；失效或放弃的方向移除或简短说明原因。尚待部署或验证时，只保留真实剩余工作和相关说明链接。

不收录实现流水账、测试数量、提交记录或“本轮未检查”清单。长期有用的实现与验收说明留在已有对应文档或记录中，项目计划按需引用。

### 决策记录的维护

只记录未来需要理解“为什么这样选择”的重要决定。简短写清日期、问题、选择、决定性原因及重要约束或代价。地区、预算、维护能力等确实影响决定时，保留相应背景；只有实际比较过且有长期解释价值时，才简述未选方案，不为补文档编造备选或理由。

旧决定被替代时，在旧条目上标明替代范围并链接新决定，保留原理由；仍有效的部分继续有效。提交、验收和部署进度在对应说明中维护，不作为每条决策的固定附录。普通修改与临时实验无需记录。

### 任务结束

只更新此次变化涉及的文档，并清理相关旧说明，不要求每次修改全部文件。不记录开发流水账，不为完整而增加低价值内容；没有影响时无需改文档。

文档入口为 `docs/README.md`。本仓库完整维护公共能力及其接口；产品集成与运营方向由服务库维护，不向本仓库复制私有资料。