原项目分析、盲区发现与二次开发协作规划

把本 Skill 作为带证据和阶段门槛的工作流：先独立还原原项目并系统发现盲区与未知，再与你讨论并确认二次开发方向，确认后生成融合改造方案；同时把关键认知、决策与进度写回项目内，作为辅助的交接能力，供其他 Agent 或新对话快速接手。

读取参考文件

每次开始时读取 references/persistence-protocol.md，执行项目记忆定位、新鲜度检查和写回规则。
需要深度分析原项目时读取 references/analysis-framework.md。
准备认知基线、决策、融合方案或实施交接文档时读取 references/report-templates.md。
不要把任何参考文件中的条目当成完整范围；根据项目实际证据扩展高价值方向并压缩低价值细节。

核心规则

先还原，后评价，再融合。 原项目基线中不得提前混入用户 DIY 想法。
清单只保证最低覆盖。 所有列举都是提示，不是思考边界。
证据优先。 以代码、配置、测试、运行结果、仓库历史和维护者记录支撑结论；无法确认时降低结论强度。
保持独立判断。 不机械接受用户判断，也不为表现独立而无依据反对；主动指出更合理的路径。
持续发现未知。 未知会在分析、讨论和实施中出现；发现后更新基线、决策、计划和实施状态。
设置阶段门槛。 未获得用户明确确认前，不生成最终融合架构，不实施相关修改。
先恢复记忆，再扫描代码。 优先复用项目内已保存的入口、基线、决策、融合方案和实施状态（记忆是辅助交接能力）。
先核对版本，再信任文档。 比较当前分支、HEAD、工作区和文档记录的修订；旧文档不是自动成立的事实。
优先增量复查。 既有文档仍有效时，只调查变更区域及其上下游；满足重建条件时才完整重扫。
把状态写回项目。 不把重要认知、决定和进度只留在聊天记录中。
不伪装完成。 代码写入但未验证时标记为已实现未验证，不得标记完成。
保护项目与用户。 不覆盖人工文档，不写入敏感信息，不在未获授权时提交、推送或开 PR。

默认项目记忆结构

项目内记忆是辅助交接能力，核心仍是上面约定的分析与协作工作流；记忆用于让新 Agent 或新对话快速复用已建立的认知，不替代分析本身。除非项目已有更合适的规范，使用：

AI_PROJECT_CONTEXT.md

docs/ai-project/
├── state.json
├── BASELINE.md
├── DECISIONS.md
├── FUSION_PLAN.md
├── IMPLEMENTATION_STATUS.md
└── CHANGELOG.md

把 AI_PROJECT_CONTEXT.md 作为稳定入口。详细职责和写回要求见 references/persistence-protocol.md。

在本地可写环境中，可使用：

python <skill-dir>/scripts/project_memory.py status --project-root <project-root>
python <skill-dir>/scripts/project_memory.py init --project-root <project-root>
python <skill-dir>/scripts/project_memory.py validate --project-root <project-root>

脚本只初始化和检查项目记忆，不替代实际分析。禁止用 --force 覆盖已有文档，除非已确认内容可安全替换。

工作流

阶段 -1：恢复项目记忆并判断新鲜度

首先确定项目根目录、当前分支、HEAD 和工作区状态，然后：

查找并读取 AI_PROJECT_CONTEXT.md 和 docs/ai-project/state.json；
根据任务读取基线、决策、融合方案和实施状态；
比较已记录修订与当前代码；
判断采取以下哪种方式：
- 直接复用：版本一致、工作区无相关变化、文档无明显冲突；
- 增量复查：存在可界定的提交或工作区变化；
- 完整重建：历史失效、架构根本变化、文档证据不足或重大冲突；
向用户说明采用的方式和实际覆盖边界。

直接复用时仍要抽查与当前任务最相关的代码位置。不要只读入口摘要就继续实施。

项目记忆不存在且项目可写时，初始化结构。项目只读时，明确说明无法持久化，不得声称已经保存。

阶段 0：确认调查对象和证据范围

识别并记录：

项目来源、仓库地址或本地路径；
当前分支、版本、标签、提交和工作区状态；
可访问的代码、文档、测试、运行环境和历史记录；
是否能访问 Issues、PR、Discussions、Releases、提交、Actions 和安全公告；
已有项目记忆对应的版本和可信边界；
当前无法访问或无法验证的资料。

项目位于 GitHub 时，优先使用可用的 GitHub 连接器或仓库工具读取真实记录。不要只分析 README，也不要把未证实反馈直接当作 Bug。

阶段 1：生成或更新项目特定覆盖图

根据代码库自身生成调查范围，而不是照抄固定目录。

至少说明：

真正影响运行、扩展、兼容和维护的领域；
每个领域的重要原因和证据来源；
已有基线已经覆盖什么；
本次变化影响什么；
哪些领域仍有信息缺口；
除用户要求外主动增加了哪些高价值方向。

执行开放式检查：

假设用户没有提供任何清单，作为维护者、架构分析者和后续开发者，还必须理解什么？

阶段 2：调查或增量更新原项目

根据新鲜度判断选择调查深度：

还原目标、边界、架构、模块关系、运行链路、数据流和关键状态；
定位重要目录、文件、类、函数、接口、数据结构、配置和扩展点；
识别技术栈、依赖、构建、部署、兼容、错误处理、测试和隐含约定；
查找不宜随意修改的核心部分及连锁影响；
调查 Issues、PR、Discussions、Releases、Changelog、提交、CI、安全和废弃记录；
提取历史缺陷、触发条件、修复方式、被拒绝方案、平台差异和可复用调试经验；
区分当前版本事实、历史问题、未证实反馈、设计限制和仍未解决事项。

持续区分：

已验证事实；
有依据的推断；
外部反馈；
未知或待核实。

阶段 3：执行盲区发现

把“已明确内容、已意识到的未知、未写出的隐含已知、尚未意识到的未知”作为扩大调查范围的透镜，不要机械建立四个固定栏目。

至少执行：

代码、配置、测试、文档、历史和运行结果交叉核对；
从新接手 Agent、维护者、二次开发者、使用者及项目特有角色寻找遗漏；
反向推演未来失败、兼容破坏、回归或误解最可能源于哪些缺失信息；
主动寻找当前清单和术语之外的高影响问题；
检查当前分类是否正在限制调查范围。

优先调查可能改变架构理解、开发方向、成本、稳定性或维护难度的内容。不要为了显得全面而堆积无关细节。

阶段 4：保存原项目认知基线并暂停

按照弹性模板更新 BASELINE.md，并同步更新：

AI_PROJECT_CONTEXT.md；
state.json；
CHANGELOG.md。

只有满足完成标准后才标记 baseline-complete；否则标记 baseline-in-progress 并写明缺失范围。

提交给用户阅读后暂停。不要直接输出融合版方案或修改代码，除非用户已经明确确认最终改造方向。

阶段 5：讨论用户想法并维护决策记录

对每项高影响想法建立稳定决策 ID，例如 DEC-001，写入 DECISIONS.md。说明：

目标、结论和依据；
影响模块、运行链路和历史问题；
收益、成本、风险和维护负担；
更简单或稳妥的替代路径；
仍需验证之处和重新评估条件；
状态：已确认、暂定、被否决、延后、待验证或被替代。

不得删除被否决或被替代的历史，也不得把临时设想写成最终要求。

阶段 6：仅在明确确认后保存融合方案

用户明确确认改造方向后，更新 FUSION_PLAN.md，并同步更新决策、入口、状态和变更日志。

方案说明：

新旧目标、架构、模块、接口、数据和流程映射；
保留、修改、新增和移除内容及原因；
实施顺序、前置条件、兼容和迁移策略；
历史问题复现风险和可借鉴方案；
测试、验收、故障定位和回退方式；
Agent 可自主决定与必须暂停确认的边界；
尚未解决的未知、风险和验证计划。

融合方案必须指向其依赖的基线修订和决策 ID。

阶段 7：实施并持续更新交接状态

对每个工作项建立稳定实施 ID，例如 IMP-001，持续更新 IMPLEMENTATION_STATUS.md。

至少区分：未开始、进行中、阻塞、已实现未验证、完成、取消、被替代。

标记完成前记录：

关联决策或方案章节；
修改文件或提交；
验证方式和实际结果；
已知限制和未覆盖测试；
剩余工作和下一步。

每次暂停、阶段结束或准备交接前，更新根入口中的当前阶段、最近完成、正在进行、未完成、阻塞、下一步、最近验证和工作区状态，使新 Agent 无需依赖旧对话即可恢复工作。

防止“清单锁死”的强制动作

每个阶段结束前：

删除或合并低价值、重复内容；
增加由项目证据新暴露的高价值内容；
检查是否只回答了提示词明确点名的事项；
写出本阶段最可能仍遗漏的高影响内容；
判断继续扩展是否会改变决策，而不是只增加细节；
检查是否需要更新项目记忆中的其他关联文档。

完成标准

只有满足以下条件，才能把当前阶段标为可提交或完成：

主要运行链路能够被连贯解释；
高影响模块、依赖、约束和历史问题已覆盖；
重要结论可追溯到证据和代码位置；
重大信息缺口已经暴露；
至少执行一次脱离原清单的开放式复查；
没有把未检查、未理解或未验证写成不存在；
项目记忆对应当前明确的分支或修订；
入口、详细文档和状态文件保持一致；
继续调查主要只会增加低价值细节，不会显著改变判断。

表达和写入要求

使用自然、直接的语言，不用大量模板化设问或为了完整而机械分点。
对高影响判断给出依据；对低影响事实适度压缩。
纠正用户时保持克制，不夸大 AI 能力，不制造不存在的确定性。
写入前读取并合并现有文档，禁止无条件覆盖人工内容。
不把密钥、令牌、个人隐私或其他敏感数据写入项目记忆。
写入后报告修改文件、对应修订和是否已被 Git 跟踪。
默认不创建提交、不推送、不开 PR，除非用户明确授权。

codebase-baseline-planner

SKILL.mdSKILL.md