GrowthMap

GrowthMap HUMAN 成长图谱白皮书

读者： GrowthMap 用户、项目负责人及审核 Agent 工作的人员

文档定位： 人类图形界面、数据管理、AI 与协作指南

版本边界： 本文依据当前 GrowthMap 代码和既有功能契约编写。打包桌面版若有少量文字或排列差异，请以实际界面为准。

1. GrowthMap 是什么

GrowthMap 是一套以“成长中的知识图谱”为核心的项目规划工具。它不只绘制分类，还会保存节点的正式字段、内容块、主线、并行方案、非树状关系、操作历史，以及人类与外部 AI Agent 的协作证据。

它适用于软件与产品开发、商业计划、研究写作、个人成长、长期目标、多方案比较，以及人类与 AI 的结构化协作。每个想法、任务、决策、问题和风险都能拥有清晰的位置、上下文与状态。

1.1 六个核心概念

  1. 项目 Project：最高层数据容器；每个项目有自己的根节点、图谱、方案线、关系和历史。
  2. 节点 Node：基本工作单元；一个节点宜只表达一项任务、决策、问题、风险或主题。类型包括 idea、concept、task、question、decision、risk、resource、note、module。
  3. 父子树与主线 Mainline：父子关系表示拆解；同一父节点可有多个子节点，其中一个可标为主线，代表优先阅读与执行路径，不会删除其他方向。
  4. 内容块 Content Block：可重复新增和排序的笔记、规格、决策、待办与风险卡片。它与摘要、描述、规则等正式字段分开保存，不会自动互相搬移或重写。
  5. 方案线 Scenario：从现有节点开启的并行方案，用于探索替代方向而不直接改变主线；成熟后可比较并合并，或归档。
  6. 关系 Relation：补充树状归属以外的影响，如 depends_on、supports、contradicts、references、blocks、relates_to。

2. 第一次开始使用

2.1 选择界面语言

使用顶部语言菜单切换“繁体中文”“简体中文”或“英文”。这只改变界面文字，不翻译项目内容。

2.2 确认授权状态

顶部显示当前状态：

  • 付费／已启用：可按 License 权限编辑。
  • 免费：显示当前使用中的项目数量。
  • 只读：可查看、搜索、导出和备份，但不能创建或修改数据。
  • 检查中：后端尚未返回权威状态，修改控件暂时关闭。

2.3 创建第一个项目

  1. 点击“新建项目”。
  2. 填写“项目名称”。
  3. 按需填写“项目描述”。
  4. 点击“创建”；也可按 Enter 提交。

名称不能只有空格。宜使用可识别名称，如“GrowthMap 官方用户白皮书”或“2026 年产品上市计划”，避免“新项目”“其他”等模糊名称。

3. 主界面导览

3.1 顶部工具栏

由左至右主要包括：GrowthMap 标志、语言选择、项目选择、方案线选择、授权状态、“新建项目”、“设置”、“搜索节点”、桌面版“数据库工作区”及“键盘快捷键”。

3.2 中央图谱

节点卡片可显示类型图标、标题、摘要、成熟度颜色、子节点数量、MAIN 主线标记；方案线采用紫色虚线外观。

  • 单击节点：选择并打开右侧面板。
  • 单击空白处：取消选择。
  • 双击节点：进入或退出聚焦模式。
  • 画布控制器：缩放、居中、适应画面。
  • MiniMap：在大型项目中快速定位。

3.3 聚焦模式

双击节点后显示该节点、其祖先、最多三层后代及同层兄弟节点，适合减少大型图谱中的视觉干扰。点击“退出聚焦”或再次双击即可离开。

4. 项目管理

4.1 切换、归档与恢复

从“选择项目”选择目标；已归档项目前显示归档图标。切换时等待同步完成，不要在同步期间快速重复切换或编辑。

在“设置”中使用：

  • 归档项目：保留数据以及读取、导出能力，但退出日常活动列表。
  • 恢复项目：将归档项目恢复为 active。

归档不是删除，适合已完成、暂停或暂时不用的项目。

4.2 导出与导入

“设置”提供：

  • 导出规格：{项目名称}_spec.md，偏结构化执行规格。
  • 导出 Markdown：{项目名称}.md，适合阅读、分享或发布。
  • 导出 JSON：{项目名称}.json，保留机器可读结构，适合交换或项目级备份。

导入 JSON：选择“设置 → 导入 JSON”，选择 GrowthMap JSON，等待成功消息和列表刷新。这是项目数据导入；“导入现有 DB”会替换整个工作区，风险完全不同。

5. 创建与管理节点

5.1 新增子节点

选择父节点，在右侧“内容 → 内容工具”中选择类型、输入标题，再点击 + 或按 Enter。新节点加入当前路径；这不等于开启新方案线。

5.2 移动、主线与删除

  • 移动：在树状模式连接节点相当于重新指定父节点；来源及其后代移至目标父节点下，操作前确认方向。
  • 设为主线：在“方案工具”的子节点列表中，对非主线节点点击“设为主线”。它只标记优先路径，不删除其他节点。
  • 删除：使用右侧垃圾桶或 Delete／Backspace，并确认提示。删除前检查子树、外部关系、内容块、是否宜改用方案线保存，以及是否已有备份。

5.3 右侧面板

四个选项卡：

  • 内容：正式数据、内容块、文档、子节点和方案。
  • AI：展开或深化节点。
  • 对话：基于当前节点上下文与 AI 讨论。
  • 历史：操作历史与 Agent 实施回报。

底部“编辑”进入正式字段和内容块编辑；“保存”保存标题、摘要与正式字段；“取消”退出本次正式字段编辑；垃圾桶删除节点。内容块自己的“保存”是独立操作，不等于面板底部的节点“保存”。

6. 节点字段完整字典

6.1 标题 Title

图上的主要名称。一个标题只表达一件事；任务用动词，如“完成登录流程测试”；决策直接写出结论，如“采用 SQLite 作为本地数据库”。

6.2 节点类型 Node type

创建子节点时选择，用于图标和语义分类，不会自动启动工作流。可用类型见 1.1 节。

6.3 成熟度 Maturity

表示内容从想法到定稿的程度：

  • Seed／种子：刚出现、信息少。
  • Rough／粗胚：已有轮廓，缺少验证或细节。
  • Developing／发展中：正在补充与实施。
  • Stable／稳定：可靠，可日常使用。
  • Finalized／定稿：已裁决完成，修改应更谨慎。

成熟度不是任务百分比；“发展中”也不等于工作流 in_progress。

6.4 摘要 Summary

用一至三句话说明这是什么、为什么重要、当前结论或下一步，使读者无需展开全部内容也能理解。

6.5 节点状态 Status

保存节点生命周期；当前界面为自由文本，默认 active。团队宜约定 active、archived、blocked、deprecated 等固定值，避免混用 done、completed、finish。

6.6 工作流状态 Workflow status

描述执行阶段；当前界面为自由文本，默认 draft。建议 draft、ready、in_progress、waiting_review、completed。节点状态偏生命周期，工作流状态偏执行阶段。

6.7 优先级 Priority

用数字表示相对优先顺序，默认 0，界面不强制范围。可统一为 0 未排序、1 最高、2 高、3 一般、4 低。

6.8 置信度 Confidence

判断或内容的可信程度，范围 0–1、步长 0.01、默认 0.5。例如 0.20 多为猜测、0.50 有部分证据、0.80 大致可靠、1.00 仅用于明确可验证内容。

6.9 Description

完整背景和目的，回答“这个节点在处理什么问题”。

6.10 Rules

必须遵守的规则和不变条件，例如“所有数据写入都必须留下操作历史”。

6.11 Constraints

外部、技术、时间、预算或权限限制，例如“仅支持 Windows 本地磁盘”。

6.12 Examples

正例、反例、输入输出示例或具体使用案例。

6.13 Questions / acceptance

待回答的问题或可验证验收条件，例如“安装后能否读取现有项目？”。

6.14 Decision notes

记录最终决策、理由、替代方案，以及未采用其他方向的原因。

6.15 文件路径 File paths

每行一条相关文件位置。它只保存文本，不代表 GrowthMap 或 Agent 自动获得文件读写权限。

7. 内容块与绑定文档

7.1 内容块

支持笔记 note、规格 spec、决策 decision、待办 todo、风险 risk。

新增时进入节点编辑模式，选择块类型，填写“块标题（可选）”和内容，点击“新增内容块”；标题和内容至少填一项。修改后点击该块的“保存”；用 ↑、↓ 排序；点击“删除”移除。块删除会提示不可恢复，不要只依赖全局撤销。

7.2 绑定文档

“已绑定文档”只保存引用，不会自动复制文档内容。

  • 文档标题：显示名称。
  • URL／路径：网址或路径文本。
  • 文档摘要（可选）：用途或内容说明。

标题和 URL 至少填一项。创建后可点击“打开”；编辑模式可“移除”。绑定路径不等于授予 Agent 权限，也不保证另一台设备能打开相同路径。

8. 方案线完整流程

当方案尚未确定、需要保护主线、比较架构／策略，或让 Agent 探索但暂不写入正式方向时使用方案线；普通扩展请新增子节点。

  1. 选择已有子节点的来源节点。
  2. 在“方案工具”点击“开启新方案线”。
  3. 填写必填名称及可选描述。
  4. 从顶部 🌿 main 旁的方案菜单切换。

界面显示“方案线模式”。合并时点击“查看并合并”，比较来源主线与方案根节点的标题、摘要、成熟度及节点／内容块数量，选择“合并到主线节点”，再点击“确认合并”。合并会结束方案线并将完整方案子树接到指定主线节点下，不是逐字段覆盖来源。

主线不能归档。切换到方案线后，可在设置的危险操作区归档当前方案；“方案线历史”显示操作与时间。

9. 搜索、热力图与关系图

9.1 搜索

在顶部输入节点名称；图上标记匹配项，下拉最多显示十条。点击结果选择，Enter 跳到第一条，Esc 清除。

9.2 热力图

按最后更新时间着色：绿色少于 1 天、黄色 1–3 天、橙色 3–7 天、红色超过 7 天、紫色从未更新。用于发现长期未维护区域，不代表质量或紧急程度。

9.3 树状与图谱模式

  • 树状模式：连线会重新指定父节点。
  • 图谱模式：连线只建立非树状关系，不改变父子结构。

拖线前务必确认模式。创建关系时切换到“图谱模式”、选类型、由来源连到目标，再在左下关系面板检查及调整权重和备注。方向示例：“发布正式版本” depends_on “完成 Windows 验收”。

9.4 关系筛选字段

  • 搜索节点：按标题缩小范围。
  • 关系范围：全部、1 跳、2 跳。
  • 方向：双向、上游、下游。
  • 最低权重：只显示达到阈值的关系。
  • 显示关系：勾选类型。
  • 权重：0–1，步长 0.05。
  • 关系依据／备注：记录理由。

10. AI 功能与 LLM Provider

10.1 创建 Provider

打开“设置 → LLM 设置”。创建配置后，AI 选项卡才有可选 Provider。Mock 不调用外部 API；真实模型的展开、深化和对话可能消耗第三方 API 额度。

10.2 展开、深化与对话

  • 展开分支：根据当前节点生成多个子节点建议。模式有“聚焦主线”“探索延伸”“挑战假设”，可填写“给 AI 的指示”。逐项“采用”或“忽略”，也可“全部采用”；建议逐项审核。
  • 深化内容：补充摘要和内容块。可只应用摘要、单独接受或忽略内容块、或全部接受；选择后才正式写入。
  • 对话：祖先路径作为上下文；输入后按 Enter 或“发送”。切换节点会重置画面对话；回答不会自动成为正式数据，重要结论应人工整理到字段或内容块。

AI 最长等待约 62 秒，界面不显示虚假百分比。请求期间若配置被修改需重新发送；出错时保留 Request ID。修改模型名称后必须先点击“保存模型”。

10.3 Provider 字段字典

  • 已保存 Provider：选择现有配置或“创建新的 Provider”；圆点表示启用状态。
  • 显示名称：供人识别的名称，必填。
  • Provider：OpenAI、Anthropic、Google Gemini、OpenClaw、Custom、OpenAI-compatible、Mock（Demo）。
  • Base URL：API 基础网址；Mock 可留空，自托管或兼容服务须填写正确路径。
  • API key 的环境变量名称：凭证语义名称，默认 GROWTHMAP_LLM_KEY_DEFAULT。
  • API Key：真实模型需要；编辑现有 Provider 时留空表示保留当前 key。桌面版使用操作系统安全存储，不把密钥放入界面、localStorage 或 SQLite；安全存储不可用时拒绝保存。
  • 模型：模型名称；留空可用 Provider 默认值。
  • 新增：清空表单以创建新 Provider。
  • 保存并使用：依次保存 metadata、安全保存凭证、设为当前选用、重新读取权威设置。部分步骤失败会明确显示，不会假装全部成功。
  • 凭证恢复：更新中断时可重新输入并完成，或重试移除。

11. 操作历史、撤销与快捷键

在“历史”中点击“查看操作历史”，可查看创建／编辑节点、创建项目、成熟度提升、AI 展开／深化、操作者类型与时间。底部另有节点 ID 缩写、创建／更新时间及 Agent 实施跟踪（如有 readback）。历史是审计数据，不是任意时间点的完整恢复。

快捷键：Esc 取消选择或关闭部分浮层；Delete／Backspace 删除并确认；Ctrl+Z／Cmd+Z 撤销可撤销操作；界面列出 E 为 AI 展开、D 为 AI 深化。内容块删除、DB 恢复等高风险操作不能只依赖撤销。

12. 数据库工作区与备份

桌面版顶部“DB”显示当前 DB 完整路径、项目数、大小、SHA-256 摘要前缀及最近备份时间。

  • 选择现有工作区：切换到另一 GrowthMap 工作区，成功后应用重启。
  • 立即备份：创建 GrowthMap 管理的备份；大型修改、导入、合并或升级前使用。
  • 导入现有 DB：先备份，再用选中 DB 替换整个当前工作区，并非附加单个项目。
  • 打开备份文件夹：在操作系统中显示备份位置。
  • 恢复：从指定备份恢复；系统先备份当前数据，期间不要关闭应用。

工作区必须位于 Windows 本地磁盘。为保护 SQLite，不支持 WSL 文件系统、UNC、网络磁盘或云同步文件夹。WSL 中的 Agent 应使用 Agent Port／API，不可直接打开 SQLite。

必须备份的时机：导入 JSON／DB、恢复、大量重组、方案合并、长时间直接协作、应用升级前，以及重要里程碑后。建议同时保留受管理 DB 备份、重要项目 JSON、可读 Markdown／规格；GrowthMap 不替代 Git、异地备份或正式灾难恢复。

13. 人类如何管理 Agent 协作

13.1 先分清两项功能

Agent 工作阶段是人工跟踪与审核面板，记录委派目标、范围、模式、进度、待审产物与结案摘要；它不会自动启动外部 Agent 或调用 LLM。

Agent Access／Agent Port是让外部 MCP 兼容 Agent 通过 localhost 图谱 API 读取或有限修改 GrowthMap 的连接层。它不授予文件系统、Git repository、shell、Provider 凭证、部署或付款权限。

13.2 启用 Agent Access

在桌面版“设置 → Agent Access／Agent Port”：

  1. 选择访问模式。
  2. 选择有效期。
  3. 启用并等待后端显示 enabled。
  4. 复制或下载通用 MCP 配置。
  5. 将 MCP server 添加到外部 Agent 客户端。
  6. 执行连接测试。

同一工作区同时只有一个有效 workspace master grant；切换 GrowthMap 项目无需重建授权。使用应用生成的设置，不要猜测路径，也不要把凭证贴到聊天或普通配置文件。

13.3 三种模式

  • 只读 Read only：可列出／读取项目、图谱和节点上下文，不能提案或直接写入；适合分析、审计、搜索。
  • 先审核 Review first：可读取并提交待审提案，人类批准后才写入；适合新 Agent、高风险项目及严格审查，是通常推荐的起点。
  • 直接协作 Direct collaboration：在授权范围内直接应用有限、类型明确、原子的节点／关系／内容块／方案线创建与更新。它不包括任意改写、删除、DB 操作、shell 或授权变更。

13.4 有效期、撤销与轮换

可选“工作阶段期间”“24 小时”“7 天”“30 天”“直到手动停用”。工作阶段期间仍是有限期限；只有“直到手动停用”是持续授权。完成后停用不需要的访问；怀疑泄漏时用“重新生成”进行原子轮换。

13.5 审核、进度与 readback

在先审核模式，逐项检查 Agent 提案的目的、目标节点、预期变化、关系方向和范围；批准后才生效，拒绝不会修改正式图谱。直接协作也应使用短期限、小批次，完成后在人类界面历史中复核。

Agent 可报告开始、进度、阻塞、完成或失败事件。readback 是外部工作证据，可包含摘要、commit、文件、测试、决策、风险、待办和证据；它只记录结果，不替 Agent 执行 repository 工作，也不等于修改正式图谱。

13.6 Agent 工作阶段面板字段

  • 工作目标：可验收交付成果，而非模糊指令。
  • 范围：节点或方案线根节点。
  • 目标：实际负责节点／方案根。
  • 工作模式：“一次性”“协作”“后台跟踪”；只是跟踪标签，不改变外部执行环境。
  • Provider（可选）：记录预期 Provider，不会自动调用。
  • 工作阶段状态：“待开始”“进行中”“待审核”“已完成”“已取消”。
  • 结果／结案摘要：完成结果、剩余问题或取消原因。
  • 产物提案：GUI 可提出待批准的子节点标题；批准才写入，退回只保留审核结果。

14. 人类与 Agent 协作示例

情形 A：只分析

人类创建目标，启用“只读”；Agent 读取项目与上下文后在外部提供分析或 readback；人类自行决定是否修改。

情形 B：提案后批准

启用“先审核”；Agent 读取最新状态并提交有理由的提案；人类逐项核对后批准或拒绝。这是新 Agent 或重要项目的推荐方式。

情形 C：可信 Agent 直接协作

先备份，启用有限期限“直接协作”；要求 Agent 小批次工作并报告里程碑；完成后查看 readback 与历史，再停用或轮换授权。

完整示例：登录功能测试计划

  1. 人类创建“登录功能”节点，在 Rules、Constraints、Questions / acceptance 填好安全规则、平台和验收条件。
  2. 创建 DB 备份，启用 24 小时“先审核”。
  3. Agent 提案创建“正常登录测试”“过期 session 测试”任务、“暴力尝试限制”风险及测试规格内容块。
  4. 人类检查并批准。
  5. Agent 若在外部 repository 完成测试，用 readback 报告真实 commit、文件、测试结果、风险和待办。
  6. 人类在节点“历史”核验证据，更新成熟度和工作流状态，最后停用 Agent Access。

15. 安全原则与常见问题

安全原则

AI 建议必须由人类审核；不在聊天中分享 token／API key；绑定路径和 file_paths 都不授权文件访问；Agent Access 仅限本地图谱 API。即使直接协作，Agent Port 也不提供删除、DB 导入／恢复、破坏性合并／归档、授权更改、文件／repository／shell、Provider key、付款或部署。授权到期或撤销后应关闭访问。

FAQ

为什么不能编辑／新建项目按钮为灰色？ 检查授权；只读或检查中会关闭修改。 为什么 AI 按钮不可用？ 可能没有已启用 Provider、Provider 不存在／停用、凭证未完成、模型未保存或请求仍在进行。 AI 出错怎么办？ 保留代码和 Request ID，检查 Provider、Base URL、模型和 API Key。 切换节点后对话消失？ 画面对话会随节点重置；重要结论请写入正式数据。 内容块排序后加载失败？ 若提示已保存，先刷新，不要立即重复移动。 方案合并后怎样？ 完整方案子树连接到指定主线节点，不逐字段覆盖来源。 Agent 看不到 GUI 当前项目？ 这是刻意设计；外部 Agent 必须明确选择项目。 Agent 写入冲突？ 数据已更新；Agent 应重新读取并重建变更，不应覆盖新数据。 MCP 配置为什么没有 token？ 桌面版使用本地 discovery 和操作系统安全凭证存储。 WSL Agent 能直接打开 SQLite？ 不能；使用 Agent Port／API。

16. 功能与版本边界

本文覆盖当前 GUI 的项目、节点树与主线、聚焦与搜索、正式字段、内容块、文档引用、方案线、关系图、热力图、AI 展开／深化／对话、Provider 管理、三种导出与 JSON 导入、桌面 DB 工作区／备份／恢复、人工 Agent 工作阶段、Agent Access、历史及 readback。

源码仓库可能另有 thin CLI 和 MCP source adapter；不可将其描述为所有桌面安装必然附带。桌面正式路径以打包的 growthmap-mcp.exe 及应用生成的通用设置为准。

GrowthMap 不会自动启动外部 Agent、不因路径引用授予文件权限、不因 Agent Access 授予 shell／repository 权限、不自动将 AI 对话写入正式数据、不保证 AI 正确，也不自动付款或部署。

17. 快速上手与填写模板

  1. 创建项目和第一层节点；指定主线。
  2. 为重要节点填写摘要、规则、限制、验收。
  3. 用内容块补充规格与风险。
  4. 不确定方向使用方案线；依赖和阻塞使用关系图。
  5. 设置 Provider 后使用 AI，逐项审核。
  6. 大型修改前备份。
  7. 初次 Agent 合作使用只读或先审核；完成后检查历史／readback 并停用访问。
标题：
节点类型：
成熟度：Seed
摘要：

Description：
Rules：
Constraints：
Examples：
Questions / acceptance：
Decision notes：

节点状态：active
工作流状态：draft
优先级：0
置信度：0.50
文件路径：

18. 提供给外部 LLM 的独立指南

本白皮书是面向人类用户的完整指南。若要让外部 LLM／Agent 连接 GrowthMap，请另行打开 [Agent／LLM 操作指南](/zh-CN/whitepaper/agent)，并把那份独立指南提供给外部 LLM；其中包含 Agent 应遵循的实际连接、工具和安全规范，不应以本篇人类 GUI 教程代替。

Personal v1 live 协作边界

Agent Access 是 Windows 用户、workspace-global 的 master grant；每次操作仍必须有明确 project_id 与 scoped intent。建议 review-first；Direct collaboration 必须明确授权。shared canonical revisions 与 CAS 会拒绝 stale write；SSE journal 只提示可能 stale state，不是 mutation truth 或 cloud DB。Windows 安装程序未签名且更新采用手动覆盖；请核对 release evidence 并备份。project SQLite 留在本地；activation 只处理授权相关数据，不接收 project DB。