codespring

CodeSpring CLI

管理项目规划：工作区、项目、任务、PRD 和思维导图。

前提条件

• 已安装 CLI：npm i -g @codespring-app/cli 或使用 npx @codespring-app/cli
• 已通过身份验证：运行 codespring auth status 进行检查。使用 codespring auth login 登录。
• 已关联项目：检查是否存在 .codespring/config.json，或运行 codespring init。

快速开始

# 1. Check auth
codespring auth status

# 2. Link project (interactive — picks workspace → project → writes config)
codespring init

# 3. Start working
codespring tasks --status todo

核心命令

命令	用途
codespring workspaces	列出可用工作区
codespring projects [--org ID]	列出项目
codespring project create --name <n>	创建新项目
codespring features	列出已关联项目的功能
codespring feature create --title <t>	创建功能
codespring tasks [--status S] [--feature ID]	按筛选条件列出任务
codespring task create --title <t> [--priority P]	创建任务
codespring task start <id>	将任务标记为 in_progress
codespring task done <id>	将任务标记为 done
codespring task update <id> --status <s>	更新任务字段
codespring prds	按功能列出 PRD
codespring prd <id>	获取完整 PRD 内容
codespring prd sync <id> --file <path>	从文件更新 PRD
codespring mindmap	获取思维导图结构
codespring mindmap set-info --title <t>	更新项目信息节点
codespring mindmap tech-stack --add '<json>'	同步技术栈
codespring mindmap features --add '<json>'	同步功能
codespring mindmap note <featureId> --text '...'	添加功能备注
codespring schema	数据架构参考
codespring node-types	思维导图节点类型参考

注意： 任务 ID 可以是 UUID 或行号（例如，task start 1 会选取列表中的第一个任务）。

输出

在终端中，所有命令默认输出 Markdown；通过管道传输时输出 JSON。 添加 --json 可强制输出 JSON，添加 --pretty 可输出格式化 JSON，添加 --md 可输出 Markdown。

Agentic 任务工作流

# 1. Find available work
codespring tasks --status todo

# 2. Claim a task (UUID or row number)
codespring task start 1

# 3. Do the work using your coding tools

# 4. Mark done
codespring task done 1

# Or create a new task
codespring task create --title "Fix login bug" --priority high

同步代码库分析结果

分析代码库后，同步分析结果：

# Sync detected technologies
codespring mindmap tech-stack --add '[{"id":"tech-react","title":"React","description":"Frontend"}]'

# Sync discovered features
codespring mindmap features --add '[{"title":"Authentication","description":"User login/signup"}]'

# Add analysis notes to a feature
codespring mindmap note feature-auth --text "Uses OAuth2 with PKCE flow..."

生成 PRD

CLI 可以读取和同步 PRD，但目前还不能生成 PRD。生成 PRD 并将 PRD 节点附加到画布上，是 CodeSpring 应用调用的直接 API 操作——请参阅 prd-management.md 和 mindmap-structure.md。cs-build-create-prd 技能封装了这一完整流程。

脚本——运行检查，不要凭目测判断

检查应由脚本完成；判断应以文字描述。 每次运行都必须得出相同结果的内容都放在 scripts/ 中，以只读方式运行，不向项目或代码库写入任何内容：

bash scripts/fetch-project.sh --out /tmp/cs-state   # snapshot the linked project's JSON; prints the projectId
node scripts/state.mjs        /tmp/cs-state         # the one-line state summary + booleans and counts
node scripts/check-map.mjs    /tmp/cs-state [--expect-core N]   # map quality + post-write verification

check-map.mjs 会检查核心功能数量、重复标题、被平铺到顶层的子功能、缺少的备注、重复 PRD 和未关联的任务；退出码 1 表示实际失败，2 表示只有警告。思维导图是否完善——例如功能是否处于侧边栏层级、子功能是否使用动词、卡片描述是否为一句话——仍由人工判断，并以文字描述。cs-build-audit-codebase/scripts/check-repo.sh 对 Git 和交付情况也执行相同的检查。

详细参考

• project-state.md — 从这里开始。 状态检测，让任何技能都能从任意位置进入；决定是否值得基于现有代码继续构建的五个问题；Understand → Plan → Build 阶段及其衔接处；地图质量注意事项和双项目情况；快速健康状况检查
• auditing-and-fixing.md — audit → verdict → map → tasks 流程；审计错误的实际来源（编排器自身的总结）；目标不断变化的现实与 git；为什么地图展示的是目标状态；重建与修复的决策表，以及是否已有用户这一关；值得排查的缺陷类别；范围控制（问题 / 以后可以添加 / 不值得添加）及未来想法的存放位置；通俗易懂的规则；幂等性 + 验证；FERB 边缘情况
• commands.md — CLI 完整参考，包含所有标志
• task-workflow.md — Agentic 任务执行模式
• analyze-codebase.md — 代码库分析清单（技术栈检测 + 深入分析功能、后端和前端；选择最精简的核心功能集合）
• mindmap-structure.md — 思维导图数据格式和节点类型（包括 PRD 桥接节点）
• prd-management.md — PRD 读取 / 同步 + 生成 / 附加 / 去重
• pitfalls.md — 故障模式与防护措施（未检查现有内容、项目错误、扁平化、PRD 重复、features --replace 追加内容、无法删除 / 移动项目）

相关技能

此 codespring 技能是共享知识库（CodeSpring 的工作方式 + CLI）。针对具体任务的技能基于它构建。每个技能在进入时都会检测项目的真实状态（project-state.md），因此用户调用哪个技能都无关紧要：

• cs-build-getting-started — 建立连接，报告项目的实际进度，并指出唯一的下一步。根据两个问题进行分流：是否有代码，以及代码是否完成任务（project-state.md 中的五个问题——绝不询问“我们是否信任它”）。
• cs-build-plan-app — 尚无代码，只有想法或通话录音。通过访谈或挖掘源材料来规划，根据功能选定平台，验证最难的部分，精简出可销售的 v1，然后编写地图和说明。
• cs-build-audit-codebase — 诊断无法完成任务的代码库（运行代码、并行使用多个专业 Agent、审计 git / CI），编写通俗易懂的 FINDINGS.md，并给出重建或原地修复的结论。
• cs-build-import-codebase — 将代码库映射到 CodeSpring 中。配合审计使用时，会构建经过纠正的目标地图，并创建基于 findings 的任务；不配合审计使用时，则记录现有内容。负责地图质量等级和节点模型。
• cs-build-ui-mockup — 根据说明制作一次性可点击原型和样式指南，与客户端共同审阅，并将修正反馈到计划中。在 PRD 之前，适用于所有带用户界面的项目。
• cs-build-create-prd — 为所选功能生成前端 / 后端 PRD（创建 PRD 的唯一事实来源）。
• cs-build-create-tasks — 将某个功能的 PRD 转换为编号的、可安全并行执行的任务列表。
• cs-build-handoff — 将完成的计划整理成付费客户端实际收到的交付包。
• cs-build-feature — 交互式构建编排器（就绪检查 → 最多 5 个子 Agent → 防止任务拆分风险的保护措施）。
• cs-build-resync-codebase — 让 CodeSpring 与已构建的代码保持同步（只读代码）。任务完成后，用它让目标地图重新反映实际情况。

如需指导用户完成仅限 Web 应用的步骤，请参阅 references/codespring-docs.md；按平台分类的 CLAUDE.md 入门模板位于仓库根目录的 claude-templates/。