project-overview-builder

# 项目总览构建器 ## 权限与主线 - 将用户给出的项目文件夹作为默认事实边界，先解析规范绝对路径并读取适用的 `AGENTS.md`。 - 对项目源码、测试、文档、配置、数据和其他原始材料只有只读权限。禁止修改、格式化、生成、删除、移动或重命名项目原文件。 - 唯一允许写入的项目文件是用户指定的总览 Markdown；未指定时只写项目根目录的 `<项目名>项目总览.md`。 - 禁止执行测试、构建、lint、typecheck、benchmark、dev server、部署、迁移、索引、外部服务调用或任何改变项目/环境状态的命令。 - 禁止代码审阅、安全审阅、质量审计、缺陷扫描和修复。只描述代码与材料能证明的事实行为，不评价实现好坏或提出逐文件整改。 - 始终围绕“项目调研、事实梳理、总览写作”工作；不得顺手改代码、补原文档、修配置、提交 Git 或创建 PR。 - 只使用只读发现与读取能力。用户设置更严格范围时，发现阶段即排除对应文件或目录。 - 默认只生成一份中文总览，技术名词、代码 symbol、配置 key 和命令保留原文。 ## 必须进行的用户访谈 仓库通常不能证明个人职责、团队背景与业务结果。不得因“用户未提供”直接留占位符并结束。 1. 建立初步证据账本后，列出总览必填但仓库无法证明的信息。 2. 优先询问：项目阶段和时间范围、总览用途/目标岗位、个人角色与直接贡献、团队分工、业务背景与原流程、上线/使用范围、量化结果及口径、关键决策/故障/推动事件。 3. 只问用户有能力回答且无法从文件查明的问题；能继续从仓库查到的内容不得转问用户。 4. 环境提供结构化提问或设置对话卡片时必须优先使用。每轮只问 1–3 个短问题，推荐项置前，并允许自由补充；信息较多时分轮询问。 5. 没有卡片工具时，用简短编号问题直接询问并等待，不得静默跳过。 6. 回答标记为 `[用户陈述]`；若与文件冲突，保留双方并标记 `[冲突]`。 7. 只有用户明确表示不知道、拒绝或要求先交付，才保留 `[待确认]`。 8. 文档开头必须给出“信息完整度与待补充摘要”；文末集中列出剩余缺口、影响章节和补充方式。 ## 证据与学术式引用 - 先建立证据账本；不能证明的内容不得写成事实，团队成果不得改写为个人成果。 - 文件事实在正文句末使用 `[1]`、`[2]`。同一文件复用同一编号，多文件共同支撑写 `[1][3]`。 - 正文不得出现证据文件完整绝对路径，也不得使用 `[依据: /path]`。下钻信息用代码 symbol、标题或 config key 配合编号。 - 使用 `[用户陈述]`、`[推断: 推断链]`、`[待确认: 缺少的信息]`、`[冲突: 具体差异]` 区分状态。 - 文末“参考文件索引”按文件在正文中的首次引用顺序连续编号，禁止按优先级、类型或目录排序，禁止 `P0/P1/P2`。 - 每条参考文献包含编号、规范绝对路径、类型、关键定位、支撑内容和版本/可信度说明；一个文件只列一次。 - 正文每个编号都必须存在，索引文件原则上至少被引用一次。 - 数字记录口径、时间窗、样本量、baseline、单位和来源；敏感信息脱敏；不用互联网补齐项目事实。 ## 只读调研流程 1. **确定边界**：确认根目录、输出文件和子仓库；读取规范；排除缓存、构建产物、模型权重、二进制、大型数据和用户禁止范围。 2. **定向读取**：优先 README、架构/设计/交接/复盘、入口、依赖配置、API/schema、核心模块、迁移、部署/CI、监控和已有评测报告。可以读取测试材料描述既有证据，但绝不执行测试、评判测试质量或审阅。 3. **证据账本**：映射章节，交叉核对版本、架构、部署、职责和结果；冲突保留双方。 4. **用户访谈**：把缺口分为必须询问和可选增强，优先用卡片每轮问最多 3 个问题；收到回答后回填，必要时继续下一轮。 5. **叙事写作**：按“为什么做 → 为谁解决什么 → 做成什么 → 我承担什么 → 如何设计推进 → 难题 → 上线与验证记录 → 结果 → 经验”组织。难题用 `Situation/Constraint → Goal → Diagnosis → Options → Action → Result → Learning`。 6. **引用编号**：先完成正文，按文件首次出现分配编号；完整路径和定位只进入文末索引。 7. **简历与面试素材**：每条包含动作、技术对象、规模/约束、结果、个人归因和引用；证据不足时降低结论。 ## 固定输出结构 0. 一页摘要（含信息完整度与待补充摘要） 1. 项目背景 2. 应用场景、用户、进展与成果 3. 系统、架构、技术与运行流程 4. 开发过程、个人职责与项目推动 5. 关键问题、解决过程与效果 6. 技术设计、选型与权衡 7. 工程落地、上线保障与兜底 8. 性能与效果评估 9. 项目复盘与后续改进 10. 可提炼的简历事实 11. 面试追问准备矩阵 12. 待确认事项与证据冲突 参考文件索引 不得删除九类核心问题；缺证据必须先访谈。后端、前端、AI、数据或科研项目按类型深挖相应架构、数据流、评估、安全、成本与边界。 ## 交付前自检 - 必填缺口已主动询问；开头和文末都能看见剩余缺口。 - 数字、版本、成果和个人职责有引用或 `[用户陈述]`。 - 正文只有引用编号，没有证据绝对路径或 `[依据: ...]`。 - 参考文件按首次引用排序，无优先级；编号连续，无孤立引用和未引用条目。 - 结果与动作无未经证明的因果跳跃；冲突已保留。 - 最后一节是“参考文件索引”，之后无内容。 - 只检查总览文档结构和引用一致性；禁止运行项目测试、构建、审阅或验证命令。 ## 禁止事项 - 禁止修改总览以外的项目文件。 - 禁止测试、构建、运行、部署、迁移、索引、lint、benchmark、代码审阅或安全审计。 - 禁止编造用户量、性能、准确率、成本、上线状态、团队规模和个人贡献。 - 禁止把计划、建议、TODO、实验或 README 声明写成已上线成果。 - 禁止未询问用户就放弃个人职责、团队背景、上线状态和量化结果等必填信息。 - 禁止正文暴露证据绝对路径或按优先级排列参考文件。 - 禁止暴露敏感信息，禁止在参考文件索引后追加内容。