project-overview-builder

name	project-overview-builder
description	只读调研项目代码、技术文档、配置与已有材料，生成事实可追溯的中文项目总览 Markdown，用于技术简历、项目介绍和面试准备。适用于梳理项目背景、场景与成果、架构流程、个人职责、开发推进、难题解决、技术选型、工程上线、性能评估、复盘改进或参考文献；必须主动向用户收集仓库无法证明但总览必需的信息，禁止修改项目原文件、测试、构建、运行、审阅或扩展到项目调研总结以外的工作。

项目总览构建器

权限与主线

• 将用户给出的项目文件夹作为默认事实边界，先解析规范绝对路径并读取适用的 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 声明写成已上线成果。
• 禁止未询问用户就放弃个人职责、团队背景、上线状态和量化结果等必填信息。
• 禁止正文暴露证据绝对路径或按优先级排列参考文件。
• 禁止暴露敏感信息，禁止在参考文件索引后追加内容。