cs-build-import-codebase

将代码库导入 CodeSpring

将真实代码仓库转化为准确的 CodeSpring 模型：核心功能 → 子功能 → 说明 → PRD → 任务。读取代码和 git；只写入 CodeSpring，绝不修改代码库。

共享知识，请阅读：codespring 技能中的 references/project-state.md（从任意状态开始、五个问题）、references/auditing-and-fixing.md（审计 → 判定 → 映射 → 任务，以及为什么映射显示的是目标）、references/analyze-codebase.md、references/mindmap-structure.md（确切的节点/边结构）、references/prd-management.md、references/pitfalls.md。然后阅读此技能中的 references/target-map.md（映射规则——节点模型、修正后的目标，以及如何保持精简）。

与语言和技术栈无关。 此处或参考资料中提到的任何具体名称都是带标签的示例，绝不代表对当前代码仓库的假设。

脚本路径相对于此技能自身的文件夹；这些技能并排安装，因此 ../codespring/scripts/… 可访问核心技能的脚本。开始时将它们解析为绝对路径——你的工作目录将是用户的代码仓库。

0. 检测项目当前状态

运行状态检测脚本，不要手动计数（codespring 技能中的 scripts/ 与此技能并排安装）：

bash ../codespring/scripts/fetch-project.sh --out /tmp/cs-state   # read-only snapshot; prints the projectId
node ../codespring/scripts/state.mjs       /tmp/cs-state          # summary line + booleans and counts
node ../codespring/scripts/check-map.mjs   /tmp/cs-state          # machine-checkable map faults, before you add to them

从本地 .codespring/config.json 读取 projectId，并在任何写入操作前打印出来。

根据现有内容采取相应操作——不要假设一切都从零开始：

• 映射已存在 → 这是更新，不是导入。打印现有核心功能及其 ID，然后运行映射质量阶梯（见下文）。按标题匹配；切勿重新创建；将游离项重新设为子项。直接跳到实际缺失的内容（说明 → PRD → 任务）。
• 尚未关联 → 关联。如果项目必须位于团队工作区中，用户需先在网页应用中创建项目（无法通过 CLI 指定或移动项目，见 pitfalls.md）。
• 已有任务 → 记录最大编号，并按顺序继续。
• 同一应用已有两个项目 → 写入任何内容前先确认哪个项目是权威项目，并告知用户。

0a. 映射质量阶梯——映射存在不代表映射质量合格

“映射已存在 → 保留它”过于武断；不可用的映射会影响基于它创建的每条说明、每个 PRD 和每项任务。包含 CLI 命令和双项目警告的完整版本见 references/target-map.md。

1. 映射是否存在？ 不存在 → 构建映射（§2–§4）。
2. 映射质量是否合格？ check-map.mjs 会检查数量、重复标题、被压平的子功能以及缺失的说明。其余部分由你判断：核心功能应为 4–8 个，且每项都应是用户能识别的侧边栏项目；子功能应是用户会执行的操作，而非输出文档的章节或表单字段组；卡片描述应为一句话，详细内容放在说明卡片中。映射可能通过所有检查，却仍然令人费解。
3. 质量合格 → 保留。 更新说明，添加任务。切勿重新创建映射。
4. 可以修复（整体大致正确，只有少数游离项）→ 原地修复并说明所做的更改：codespring feature update <subId> --parent <coreId>、codespring feature delete <dupId> --yes、codespring feature update <id> --title "..."。
5. 无法修复（核心功能过多、用输出章节充当功能、结构不连贯）→ 不要勉强修补。 明确解释原因，建议创建一个映射清晰的新 CodeSpring 项目，并说明旧项目会保留为历史记录。创建第二个项目前必须获得明确确认——绝不可擅自创建。 同一应用存在两个项目会造成后续混淆，因此必须是经过充分解释的慎重选择，并告知用户哪个项目现为权威项目。（真实案例：一次导入创建了 13 个核心功能，无法使用；后来创建了一个包含 6 个清晰功能的新项目并取而代之；两个项目都仍然存在，且没有 project delete 命令。）

1. 是否有审计？

这是唯一会改变输出的输入。

	行为
无审计	记录现有内容——应用当前的实际情况。
审计 + 结论	构建修正后的目标图谱——应用应该是什么样，简化为非专家也能识别的核心功能。

如果没有审计，请先询问五个问题（project-state.md），再进行导入——应用是否实现了所需功能；是否会出错，或将无法验证的数据作为事实呈现；架构是否能支持所需功能；能否以可扩展的方式构建；用户能否顺畅使用。只要有一项回答“否” → 就先提供审计。 不要问“你信任这段代码吗”，也不要把“能运行”当成五个“是”——“代码能运行”不等于“代码能完成任务”。

然后运行快速健康状况检查（project-state.md），因为用户通常无法凭现有认知回答第 2、4 和 5 个问题。六个问题征兆：没有测试/CI、部署未设门禁、本地克隆落后于远程版本、错误被吞掉、发布的源代码中包含凭据、记录仅存在于浏览器中或参考数据被硬编码。出现两个或更多 → 停止并明确提出审计：“我发现了 6 项征兆中的 4 项，这些问题通常意味着应用在绘制图谱前需要先诊断。要我先运行 cs-build-audit-codebase 吗？” 不要悄悄导入一团乱麻——对损坏应用绘制的图谱不值得信任。如果用户拒绝，就导入现有内容，并说明图谱记录的是应用当前的行为，包括缺陷。

2. 分析代码

按照 analyze-codebase.md 执行：绘制前端图谱（路由、组件、用户看到的内容、导航）和后端图谱（API 路由及其对应的功能、数据模型、安全性、共享系统——支付/额度、任务/cron、存储、身份验证、环境变量——以及基础设施）。确定实际技术栈。阅读文件，不要猜测。走审计流程时，你已经掌握了其中大部分信息——复用已有发现，不要重新推导。

3. 确定功能——最小且易于识别的集合

规则和失败案例详见 references/target-map.md。简而言之：

• 核心功能 = 用户会在侧边栏/导航级别上指出的内容。目标是 4–8 个。 第一次实际运行产生了 13 个令人困惑的核心功能；调整方向后，得到 6 个清晰的核心功能。尽可能努力缩小集合。
• 子功能 = 用户会执行的操作。用动词表达。保存一个客户端。比较两个属性。导出 PDF。
• 不要重复这个错误：不要把报告/页面区块或表单字段组变成子功能。 报告区块是某个功能输出的一部分；表单字段组是某个功能输入的一部分。十二个报告区块应算作一个功能，加上一条恰当的备注，而不是十二个功能。
• 卡片描述只保留一个简短句子。所有详细信息都放入通过桥接节点附加到该功能的备注卡中——绝不要放在卡片描述里。 节点模型（功能节点 → 卡片 → 桥接节点 → 备注卡，以及桥接节点 → PRD 桥接节点 → PRD）见 references/target-map.md；具体架构见 mindmap-structure.md。第一次实际运行恰恰在这点上失败了：卡片描述过长，且把输出区块提升为子功能，导致有 13 个不可用的核心功能。
• 通过 CLI 添加的备注只能用于根功能，因此子功能的详细信息应写入其父核心功能的备注（pitfalls.md §5）。

在审计流程中，只有当某项 1 类修复无处可放时，才添加当前应用缺少的功能（例如，为仅存在于浏览器中的记录提供持久存储；添加目前不存在的登录功能）。2 类“以后可以添加”的想法绝不能成为功能（auditing-and-fixing.md §4a）。

询问应用的功能是否已经完整，还是仍在开发中。 如果仍在开发中，在最终确定列表前，询问哪些内容已经计划但尚未构建——缺少代码不能证明某项功能缺失；没有任何链接指向的页面可能是尚未完成的模块，而不是死胡同或独立产品。

写下任何内容之前，先向用户复述列表，并请他们删减。

4. 编写映射（CLI）

codespring mindmap set-info --title "..." --description "..." --github "<repo url>"
codespring mindmap tech-stack --replace --add '[{"id":"tech-...","title":"...","description":"Frontend"}, ...]'
codespring mindmap features --add '[{"title":"Dashboard","description":"..."}, ...]'   # CORE features; keep the returned ids
codespring feature create --parent <coreId> --title "..." --description "..."           # sub-features
codespring mindmap note <coreId> --title "How it works — X" --text "$(cat note.txt)"    # one per core feature; redirect output to /dev/null

幂等性（auditing-and-fixing.md §8）： 先按标题进行差异比较，只添加缺少的内容。codespring mindmap features --replace 并不会替换内容——它只会追加并创建重复项。 如果出现重复项，请使用 codespring feature delete <id> --yes 恢复，该命令有效，并会级联删除。

每个核心功能的备注都要包含 analyze-codebase.md §8–9 中要求的深度；在审计流程中，还要包含三项内容：该功能应该做什么、目前如何运作，以及当前存在什么问题（严重性 + 文件引用；重建时还需列出“不要重新引入”的约束）。PRD 生成器会读取此备注作为上下文，因此备注过于简略会生成过于简略的 PRD。更新现有备注时，先阅读原文，并保留仍然正确的内容。

5. 说明映射的含义

向用户用一句话说明，以避免实际误解：该映射展示的是修正后的目标结构，而不是当前结构——因此，在任务完成之前，它不会与代码库的结构一致；看板展示的就是两者之间的差距。 原因见 references/target-map.md；这是有意为之，并且适用于两种判定结果。

6. PRD——通过 cs-build-create-prd

不要重新实现 PRD 的处理流程。对每个核心功能，都使用 cs-build-create-prd（Both frontend + backend）；它会记录共享的后端契约，并正确附加 PRD 桥接节点。注意其 ≥120s 的超时时间和去重规则。除非用户提出要求，否则绝不要重新生成已有的 PRD——先阅读它，告知用户它已存在，并提出是否需要刷新。绝不要为没有备注的功能生成 PRD。

7. 任务——两条路径各不相同，这一点至关重要

只有 类别 1（真实问题） 会转化为任务。每个任务都必须关联且仅关联一项核心功能，并标注严重程度（Critical → urgent、High → high、Medium → medium、Low → low）；标题为一句话，详情写入描述，并延续现有编号。

未来设想在 CodeSpring 中无处安放，也绝不能转化为任务——任务列表意味着已承诺要开展的工作。类别 2 和类别 3 应放在仓库中的 FINDINGS.md，分列在两个标题明确的章节中，每个章节附上一句原因：“以后可以添加——现阶段有意不做” 和 “不值得添加”。绝不能放在地图或看板中，也不能放入 PRD（auditing-and-fixing.md §4a——这是 FERB 已知的产品缺陷）。

判定 = 重建 → 两组不同的任务。

1. 按规范构建任务——每项功能／子功能对应一个任务，先处理基础部分。
2. “应避免的错误”任务——原产品中发现的每项重大缺陷对应一个任务，将其作为明确的禁止重新引入约束，并附上具体示例。这第二组任务正是导入前进行审计的全部意义——没有它，重建就会重现同样的静默故障、硬编码表格和重复逻辑，因为新计划中没有任何内容说明不得这样做。请将其写成可验证的约束：
   • “参考数据应存放在带日期的记录中，而不是直接写入代码的值。修改费率不能通过编辑应用来实现。”
   • “查找不到结果时，必须明确说明。任何代码路径都不得在发生错误时填入零值或空白。”
   • “计算逻辑只能有一份，所有内容都必须导入这一份。”
   • “发布报告时，应保存输入、结果以及生成这些结果所用的费率年份——这样以后修正费率时，不会改变客户已经看到的内容。”
   • “任何人的身份都不能来自请求正文。请求中的标识符是目标，使用前必须检查其归属。”

判定 = 原位修复 → 一组任务。 每项缺陷对应一个任务，在缺陷所在位置处理，并在描述中注明文件路径（面向用户的审查结果中没有路径；任务需要路径，因为 Agent 必须据此采取行动）。处理顺序：先处理静默故障，再处理错误输出，然后处理结构性工作，最后润色——也可以遵循审计中建议的修复顺序。

未进行审计 → 任务来自 PRD，而不是审查结果。此时请交由 cs-build-create-tasks 处理；它负责生成源自 PRD 的任务列表。此技能只编写源自审查结果的任务，因为只有这里包含这些审查结果。

未验证的审查结果应转化为调查任务，并保留其标签——绝不能将其写成确定的修复任务。

8. 验证（pitfalls.md、auditing-and-fixing.md §9）

运行检查，不要靠目测：

bash ../codespring/scripts/fetch-project.sh --out /tmp/cs-verify
node ../codespring/scripts/check-map.mjs   /tmp/cs-verify --expect-core <the count you intended>

• node-features.items.length 等于预期的核心功能数，且没有子功能被提升到顶层。 使用 codespring feature update <subId> --parent <coreId> 重新关联任何错位的子功能；保留一份子功能 → 核心功能映射表，以便再次运行时只需执行一条命令。
• 不得存在重复功能（按标题判定）或重复 PRD（按功能 + 类型判定）。
• 每项核心功能对应一条备注。每项任务都必须关联一项功能并标注严重程度。
• 非零退出码表示确实失败：先修复，再报告。然后报告差异：创建 N 项、更新 N 项、跳过 N 项。提供项目链接 https://v2.codespring.app/project/<projectId>。

9. 可选：独立审计地图（仅限不审计路径）

如果走审计路径，请跳过此步骤——你已经有审计结果。否则，启动一个后台子 Agent，提供一份完全自包含的说明，且不提供任何导入工作的上下文，以确保比较公正：

你是一名独立审计员。只读：不要修改代码库或 CodeSpring 地图。

1. 盘点整个代码库——每条路由、每个页面、每张表 + 枚举、每个外部提供方、Webhook、cron/作业，以及共享的后端契约（付款/额度/退款、作业管线、存储约定、身份验证、环境变量）。
2. 阅读 CodeSpring 中记录的所有内容——通过 codespring CLI 阅读每项功能的说明和 PRD。
3. 严格比较并报告，优先关注共享后端缺口和冲突风险（新增功能中风险最高的部分）。标出代码中所有未记录的内容、任何可能破坏或重复共享系统的内容，以及文档中缺少关键后端细节的内容——每项都要标注严重程度，并附上准确的文件/路由/表引用；另外，列出建议添加到 CodeSpring 的内容。

完成后报告结果，并提出将清单整合到说明/PRD 中，或移交给 cs-build-resync-codebase。

如何判断结果是否理想

• 地图只保留非专家也能识别的最少数量的核心功能——不包括报告章节，也不包括表单字段组。
• 如果进行了审计，地图就是修正后的目标版本，并已用一句话告知用户；如果没有审计，则如实记录现状。
• 没有重复内容：根据阶梯标准评估现有地图后，原样保留或就地修复；按标题匹配功能；重新归类位置不当的条目；保留现有 PRD。
• 只有在获得明确确认后，才创建第二个 CodeSpring 项目，并说明原因和指定权威项目。
• 未来想法应写在两个指定的 FINDINGS.md 章节中，不应放在地图上或 Kanban 中。
• 每项核心功能都有真实的“工作原理”说明，且每份 PRD 都由一份说明生成。
• 重建时，应有一组独立的“避免的错误”任务，确保原项目的缺陷不会再次出现。就地修复时，每项缺陷都应在其实际所在位置对应一项任务。